# Public API Query Guide

This guide describes how bots should query Pitt Landscape's public, SQL-backed API. The recommended interface is HTTP against `/api/public/*`, not direct datastore queries.

## Conventions
- Use the read-only public endpoints.
- Filter with public-safe params only.
- Prefer slugs for services and service areas.
- Use `limit` conservatively.
- Respect cursor pagination where provided.
- Read and surface freshness metadata from the `meta` object.

## Discovery endpoints
- `GET /api/public/index`
- `GET /api/public/openapi.json`

## Core list endpoints
- `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?}&limit={6..24}`

## Context and insight endpoints
- `GET /api/public/provider-context?service={serviceSlug}&city={city?}&neighborhood={neighborhood?}&lat={lat?}&lng={lng?}&radiusMiles={radius?}`
- `GET /api/public/insights?service={serviceSlug?}&serviceType={serviceTypeSlug?}&area={areaSlug?}&city={cityName?}`

## Common query patterns

### List all service types
`GET /api/public/service-types`

### List services for a service type
`GET /api/public/services?serviceType=landscape-design`

### List cities for a county
`GET /api/public/service-areas?level=city&parent=salt-lake-county`

### Get photos for a service in an area
`GET /api/public/photos?service=site-preparation&area=salt-lake-city&limit=6`

### Get FAQs for a service in a city
`GET /api/public/faqs?service=sprinkler-installation&area=salt-lake-city`

### Get recent public project summaries for a city
`GET /api/public/projects?city=Salt%20Lake%20City&limit=6`

### Get provider context for a service + city
`GET /api/public/provider-context?service=concrete-contractors&city=Draper`

### Get broader insights for a service + area
`GET /api/public/insights?service=landscape-architecture&area=salt-lake-city`

## Pagination and freshness
- list endpoints may accept `limit` and `cursor`
- paginated responses return `nextCursor`
- list and context responses include:
  - `meta.generatedAt`
  - `meta.dataVersion`
  - `meta.lastContentUpdate`

## Validation behavior
- slug-based endpoints validate incoming slugs before querying
- invalid slugs return a helpful error and may include valid alternatives

## Authentication
- anonymous access is allowed
- trusted callers can register via `POST /api/public/auth/register`
- trusted headers:
  - `x-ai-actor: {actorId}`
  - `Authorization: Bearer {actorApiKey}`
  - optional: `x-api-key: {actorApiKey}`

## Error handling
- `400` for invalid query parameters
- `401` for invalid trusted credentials
- `403` for blocked actors
- `429` for rate limiting

When rate limited, check:
- `Retry-After`
- `X-RateLimit-Limit`
- `X-RateLimit-Remaining`