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

# Chats

> Start chats, append turns, list history, and poll for assistant output.

Chats in the public API are asynchronous. Starting or continuing a conversation returns ids immediately; you poll a single message endpoint until the assistant's `response` field is present.

<Frame caption="A completed chat in Chief — the assistant's answer, grounded in the project's files.">
  <img src="https://mintcdn.com/chief-2d405d1a/QGBlzHNeqRlizFjv/images/demos/web-chat.png?fit=max&auto=format&n=QGBlzHNeqRlizFjv&q=85&s=c2f2110e915562fb9c0f10af203a47d0" alt="A Chief chat answering a summarize-uploads question with a two-bullet response citing the project's files" width="2000" height="729" data-path="images/demos/web-chat.png" />
</Frame>

## Lifecycle overview

```mermaid theme={null}
sequenceDiagram
  participant Client
  participant API as Chief API
  participant WF as Workflow

  Client->>API: POST /v1/chats {prompt}
  API->>WF: Kick off chat
  API-->>Client: 202 chat_id, message_id
  loop Until response present
    Client->>API: GET /v1/chats/{id}/messages/{mid}
    API-->>Client: prompt/response (partial or complete)
  end
```

There is no lifecycle enum on messages in v1. Treat the appearance of `response` as completion.

## Start a new chat

`POST /v1/chats` accepts a `CreateChatRequest` body:

* **`prompt`** (required) — user message that starts the thread
* **`intelligence`** — `auto` (default), `fast`, `expert`, or `research`
* **`provider`** — `automatic`, `anthropic`, `openai`, or `google`
* **`skills`** — array of skill names to preload
* **`public_data`** — set `false` to disable public web search for this turn
* **`scope`** — optional knowledge scope (assets, chats, labels, concepts, projects, views)

Response (`202`):

```json theme={null}
{
  "chat_id": "chat_d8aad64dib2c7m3ae7j0",
  "message_id": "message_d8aad64dib2c7m3ae7jg",
  "created_at": "2026-05-23T10:15:30Z"
}
```

Poll `GET /v1/chats/{chat_id}/messages/{message_id}`.

## Append a turn

`POST /v1/chats/{id}/messages` uses the same optional fields as create, with `prompt` required. The chat id is in the path.

Response (`202`):

```json theme={null}
{
  "message_id": "message_d8aad64dib2c7m3ae7k2",
  "created_at": "2026-05-23T10:16:05Z"
}
```

## Read one message

`GET /v1/chats/{id}/messages/{mid}` returns a `Message`:

| Field        | Notes                                                          |
| ------------ | -------------------------------------------------------------- |
| `id`         | Message id                                                     |
| `prompt`     | User text (markdown); omitted until written                    |
| `response`   | Assistant answer (markdown, final only); omitted until written |
| `created_at` | When the message row was persisted                             |

## List messages (ids only)

`GET /v1/chats/{id}/messages` returns summaries (`id`, `created_at`) without body text. Fetch each message individually for content.

## Chat metadata

`GET /v1/chats/{id}` returns `chat_id` and optional `modified_at` (latest message time). It does not include messages.

## List chats

`GET /v1/chats` returns chats newest first with cursor pagination:

| Query       | Purpose                                                |
| ----------- | ------------------------------------------------------ |
| `after_id`  | Pass previous page's `last_id` for the next page       |
| `before_id` | Paginate backward (mutually exclusive with `after_id`) |
| `limit`     | Page size (1–100, default 25)                          |

Response shape:

```json theme={null}
{
  "data": [{ "chat_id": "...", "created_at": "..." }],
  "first_id": "...",
  "last_id": "...",
  "has_more": true
}
```

## Scoping knowledge

Use `scope` on create or send to limit what the assistant may consult. Tenancy always comes from `X-Project-Id`; do not put project ids in `scope` unless you are explicitly widening to additional projects via `scope.project_ids`.

Example—question only your uploaded report:

```json theme={null}
{
  "prompt": "What risks does the ACME product roadmap highlight?",
  "scope": {
    "asset_ids": ["asset_d8aad64dib2c7m3ae7j1"]
  }
}
```

## Related endpoints

See the **API reference** tab under **Chats** for request and response schemas, or start with [Introduction](/api-reference/introduction).