Chats

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. These are the same threads end users see in the app. How chats work explains what a chat is in product terms — grounding, citations, and how a thread holds context.

A Chief chat answering a summarize-uploads question with a two-bullet response citing the project's files — A completed chat in Chief — the assistant's answer, grounded in the project's files.

Lifecycle overview

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):

{
  "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):

{
  "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:

{
  "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:

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

FAQ

How do I know when a chat response is ready?

There is no lifecycle enum on messages in v1. Poll GET /v1/chats/{id}/messages/{mid} and treat the appearance of the response field as completion.

Can I stream tokens as the assistant writes?

Not in v1. response holds the final answer only and is omitted until it is written, so polling returns either nothing or the complete answer.

How do I limit which files the assistant can read?

Pass scope on create or send. For example, scope.asset_ids restricts the turn to specific uploaded files. Labels, chats, concepts, and views can also scope a turn.

Do I need to put my project id in scope?

No. Tenancy always comes from the X-Project-Id header. Only set scope.project_ids when you are deliberately widening a turn to additional projects.

Why does listing messages return no text?

GET /v1/chats/{id}/messages returns summaries — id and created_at only. Fetch each message individually to get its prompt and response.

See the API reference tab under Chats for request and response schemas, or start with Introduction.

Get started

Guides

Lifecycle overview

Start a new chat

Append a turn

Read one message

List messages (ids only)

Chat metadata

List chats

Scoping knowledge

FAQ

​Lifecycle overview

​Start a new chat

​Append a turn

​Read one message

​List messages (ids only)

​Chat metadata

​List chats

​Scoping knowledge

​FAQ

​Related endpoints

Lifecycle overview

Start a new chat

Append a turn

Read one message

List messages (ids only)

Chat metadata

List chats

Scoping knowledge

FAQ

Related endpoints