Build on Chief — MCP server, REST API, and CLI

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.

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"]
  }
}

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

Get started

Guides

Chats

Lifecycle overview

Start a new chat

Append a turn

Read one message

List messages (ids only)

Chat metadata

List chats

Scoping knowledge

​Lifecycle overview

​Start a new chat

​Append a turn

​Read one message

​List messages (ids only)

​Chat metadata

​List chats

​Scoping knowledge

​Related endpoints

Lifecycle overview

Start a new chat

Append a turn

Read one message

List messages (ids only)

Chat metadata

List chats

Scoping knowledge

Related endpoints