# Breezy Public API

Use `/openapi.public.json` as the machine-readable customer API contract.
Do not use `/openapi.json` for customer-facing tools; it contains internal
router surfaces.

Important docs:

- Overview: ./index
- Authentication: ./authentication
- API keys: ./api-keys
- Principal types: ./principal-types
- Staff impersonation boundary: ./staff-impersonation
- Pagination and filtering: ./pagination
- Errors: ./errors
- Rate and safety expectations: ./rate-safety
- Workflow examples: ./examples
- Generated API reference: ./api-reference

Auth summary:

- User JWTs use `Authorization: Bearer <jwt>`.
- Service-principal API keys use `Authorization: Bearer bzy_live_...`.
- API keys cannot manage API keys.
- Staff/admin/widget/webhook/dev-test procedures are excluded from the public
  OpenAPI artifact unless explicitly allowlisted later.