Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.chief.bot/llms.txt

Use this file to discover all available pages before exploring further.

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. 
https://api.storytell.ai
The OpenAPI specification is available without authentication: 
https://api.storytell.ai/v1/openapi.yaml

​
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. 
X-API-Key: pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
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: 
X-Project-Id: project_d8a4td4dib27i4beefb0
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.
StatusDescription
200Successful request.
202Accepted — async work started (chat kickoff, message send).
400Invalid parameters, validation failure, or missing X-Project-Id.
401Missing, invalid, or revoked PAT.
404Resource not found or not accessible in this project.
500Unexpected server error.
See Errors for the error envelope and stable code values.

​
Error envelope

Every error response uses the same JSON shape: 
{
  "code": "publicapi.auth.invalid",
  "humane": "The provided API key is invalid or has been revoked.",
  "statusCode": 401
}
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.