Skip to main content
Understand how to authenticate, scope requests to a project, and interpret responses from the Chief Public API.

​
Base URL

The Chief Public API is built on REST principles. Use HTTPS for every request.
The OpenAPI specification is available without authentication:

​
Authentication

Authenticate with a Personal Access Token (PAT) in the X-API-Key header. PATs are created in the Chief app under Settings → API tokens.
PATs use the pat_ prefix followed by 32 characters. The full secret is shown only once at creation. Revoked or invalid keys return HTTP 401 with code publicapi.auth.invalid.
Store PATs in a secret manager. Do not commit them to source control or embed them in client-side code.

​
Project scoping

Every project-scoped endpoint also requires X-Project-Id:
Organization and workspace tenancy are inferred from the project. Missing or malformed project headers return HTTP 400 with code publicapi.tenancy.project.missing.

​
Response codes

Chief uses standard HTTP codes to indicate success or failure.
See Errors for the error envelope and stable code values.

​
Error envelope

Every error response uses the same JSON shape:
Use code for branching and analytics. Use humane for display copy.

​
Async operations

Chat endpoints are asynchronous in v1. POST /v1/chats and POST /v1/chats/{id}/messages return immediately with ids; poll GET /v1/chats/{id}/messages/{mid} until response is present. See the Chats guide. Asset uploads use a three-step flow: create slot, PUT to blob storage, then complete. Poll GET /v1/assets/{id} until status is ready or failed. See the Assets guide.

​
FAQ

List endpoints for chats and assets use cursor-based pagination with after_id, before_id, and limit. Pass the previous page’s last_id as after_id to move forward. See Pagination.
PAT management is only available in the Chief UI (Settings → API tokens), not through the public /v1 API.
All public endpoints are under the /v1 prefix. Breaking changes will ship under a new prefix when introduced.
CORS preflight is supported for documented methods. For production, call the API from your backend so PATs never ship to clients.