# Public Index Manifest

Version: 1.4
Last updated: 2026-03-26

This is the entry point for bots. It summarizes canonical routes, allowed lists, projections, and exclusions.

## Canonical route map
- serviceType -> `/services/{serviceType.slug}`
- service -> `/services/{serviceType.slug}/{service.slug}`
- serviceArea -> `/utah/{county.slug}/{city.slug}/{neighborhood.slug?}`
- page -> `/{page.slug}`

## Public insights API (read-only)
Endpoint:
- `GET /api/public/insights`

Related public discovery endpoints:
- `GET /api/public/index` (capability and endpoint metadata)
- `GET /api/public/openapi.json` (OpenAPI 3.1 machine contract)
- `GET /api/public/service-types`
- `GET /api/public/services?serviceType={serviceTypeSlug?}`
- `GET /api/public/service-areas?level={state|county|city|neighborhood?}&parent={parentAreaSlug?}`
- `GET /api/public/photos?service={serviceSlug?}&area={areaSlug?}&projectPhase={before|in_progress|after?}`
- `GET /api/public/faqs?service={serviceSlug?}&area={areaSlug?}&page={pageSlug?}`
- `GET /api/public/projects?city={cityName?}&service={serviceSlug?}`
- `GET /api/public/provider-context?service={serviceSlug}&city={city?}&neighborhood={neighborhood?}&lat={lat?}&lng={lng?}&radiusMiles={radius?}`

Working examples (copy-paste ready):
- `GET /api/public/service-types` — list all service categories
- `GET /api/public/services?serviceType=landscape-design` — list landscape services
- `GET /api/public/insights?service=landscape-architecture&city=Salt Lake City` — insights for a service + city
- `GET /api/public/provider-context?service=concrete-contractors&city=Draper` — project counts by location
- `GET /api/public/photos?service=retaining-walls&limit=5` — photos for a service
- `GET /api/public/faqs?service=sprinkler-installation` — FAQs for a service
- `GET /api/public/projects?city=Murray&limit=6` — recent projects in a city
- `GET /api/public/service-areas?level=city&parent=salt-lake-county` — cities in a county

Slug validation:
- All endpoints validate slug parameters before querying. If an unknown slug is provided, the response includes the full list of valid slugs so you can retry with the correct value.

Authentication:
- Anonymous access is allowed.
- Register for a trusted key: `POST /api/public/auth/register`
- Trusted request headers:
  - `x-ai-actor: {actorId}`
  - `Authorization: Bearer {actorApiKey}`
  - Optional alternative: `x-api-key: {actorApiKey}`

Rate limiting:
- Per IP and per actor limits are enforced.
- Verified actors receive higher limits than anonymous callers.
- Exceeded limits return `429` with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers.

Pagination and freshness:
- List endpoints use `limit` + `cursor` request params and return `nextCursor`.
- List and context responses include `meta.generatedAt`, `meta.dataVersion`, and `meta.lastContentUpdate`.

Parameters (any one required):
- `service` (service slug)
- `serviceType` (service type slug)
- `area` (service area slug)
- `city` (city name)

Response highlights:
- `projectCount` (aggregate)
- `revenueBand` (aggregate, range only)
- `reviewSummary` (count + average)
- `photos` (limited set)

## Indexable lists and filters
- Service types: list all
- Services: list all or by service type
- Service areas: list by level and parent
- Gallery photos: filter by service, area, and/or `projectPhase`
- FAQs: filter by service, optional service area, or page
- Projects (summary only): filter by city and/or service with a small limit (6-12)

## Visibility rules
- Only published SQL-backed content and public-safe records.
- Exclude routes or rows marked `noindex` where present.

## Public projections
Use the projections defined in `query-guide.md` and `data-model.md`.

## Exclusions
Never expose these document types or fields:
- `contact`, `webLead`, `jobApplication`, `emailTemplate`, `reviewRequest`, `projectFeedback`
- Any PII (names, emails, phones, addresses)
- Pricing, costs, margins, internal IDs
- Geocoordinates, bounds, or place IDs

## Supporting docs
- `overview.md`
- `site-map.md`
- `data-model.md`
- `query-guide.md`
- `examples.md`
- `constraints.md`
- `freshness.md`