> ## 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.

# Introduction

> General concepts, response codes, and authentication for the Chief Public API.

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**](https://chief.bot/settings/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`.

<Warning>
  Store PATs in a secret manager. Do not commit them to source control or embed them in client-side code.
</Warning>

## 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.

| Status | Description                                                        |
| ------ | ------------------------------------------------------------------ |
| `200`  | Successful request.                                                |
| `202`  | Accepted — async work started (chat kickoff, message send).        |
| `400`  | Invalid parameters, validation failure, or missing `X-Project-Id`. |
| `401`  | Missing, invalid, or revoked PAT.                                  |
| `404`  | Resource not found or not accessible in this project.              |
| `500`  | Unexpected server error.                                           |

<Info>
  See [Errors](/api-reference/errors) for the error envelope and stable `code` values.
</Info>

## Error envelope

Every error response uses the same JSON shape:

```json theme={null}
{
  "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](/guides/chats).

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](/guides/assets).

## FAQ

<AccordionGroup>
  <Accordion title="How does pagination work?">
    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](/api-reference/pagination).
  </Accordion>

  <Accordion title="How do I create or revoke API keys?">
    PAT management is only available in the Chief UI ([**Settings → API tokens**](https://chief.bot/settings/tokens)), not through the public `/v1` API.
  </Accordion>

  <Accordion title="How does API versioning work?">
    All public endpoints are under the `/v1` prefix. Breaking changes will ship under a new prefix when introduced.
  </Accordion>

  <Accordion title="Can I call the API from a browser?">
    CORS preflight is supported for documented methods. For production, call the API from your backend so PATs never ship to clients.
  </Accordion>
</AccordionGroup>