Quickstart

In a few minutes, your own code will be answering questions over your team’s entire knowledge base — no retrieval pipeline, no embeddings, no infrastructure to run. This guide takes you from zero to that first answer with plain curl. For authentication and HTTP semantics, see Introduction.

Prefer not to write code? Your AI coding agent can do all of this for you — connect it to Chief and just ask. See Use Chief with your AI coding agent. This page is the manual, do-it-yourself path.

Prerequisites

A Chief account with access to a project
A PAT from Settings → API tokens — the help center walks through creating one
Your project id (project_…)

Export variables for the examples:

export CHIEF_API_KEY="pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export CHIEF_PROJECT_ID="project_xxxxxxxxxxxxxxxxxxxx"
export CHIEF_BASE_URL="https://api.storytell.ai"

Start a chat

POST /v1/chats starts an async workflow and returns ids immediately:

curl -sS -X POST "$CHIEF_BASE_URL/v1/chats" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CHIEF_API_KEY" \
  -H "X-Project-Id: $CHIEF_PROJECT_ID" \
  -d '{"prompt": "What are the three most important themes across our ACME uploads?"}'

Example response (202 Accepted):

{
  "chat_id": "chat_d8aad64dib2c7m3ae7j0",
  "message_id": "message_d8aad64dib2c7m3ae7jg",
  "created_at": "2026-05-23T10:15:30Z"
}

Poll for the response

Poll until response appears on the message:

CHAT_ID="chat_d8aad64dib2c7m3ae7j0"
MESSAGE_ID="message_d8aad64dib2c7m3ae7jg"

curl -sS "$CHIEF_BASE_URL/v1/chats/$CHAT_ID/messages/$MESSAGE_ID" \
  -H "X-API-Key: $CHIEF_API_KEY" \
  -H "X-Project-Id: $CHIEF_PROJECT_ID"

Use exponential backoff between polls and cap total wait time in production.

Continue the conversation

curl -sS -X POST "$CHIEF_BASE_URL/v1/chats/$CHAT_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $CHIEF_API_KEY" \
  -H "X-Project-Id: $CHIEF_PROJECT_ID" \
  -d '{"prompt": "Summarize that in three bullet points."}'

What you just built

That’s the whole loop: your code asked a question, Chief answered it from your project’s knowledge, and you continued the thread — with no retrieval pipeline or infrastructure to run. That same primitive is the foundation for a Q&A feature in your app, a scheduled digest, an agent that reads your project, and more. See What you can build for where to take it.

FAQ

Where do I get an API key?

Create a Personal Access Token in the Chief app under Settings → API tokens. The full secret is shown only once, at creation.

Why did POST /v1/chats return 202 instead of an answer?

Chat endpoints are asynchronous. The 202 carries the ids; poll GET /v1/chats/{id}/messages/{mid} until the response field appears.

How long should I wait between polls?

Use exponential backoff and cap total wait time in production. There is no lifecycle enum to watch — the arrival of response means the turn is done.

Do I need to write code at all?

No. Connect an AI coding agent over MCP and ask in plain English — see Use Chief with your AI coding agent. The chief CLI covers shell and CI without code too.

I got a 400 mentioning the project header.

Every project-scoped endpoint needs X-Project-Id alongside X-API-Key. A missing or malformed value returns publicapi.tenancy.project.missing.

Next steps

What you can build — concrete outcomes built on this loop
Chats guide — scope, intelligence modes, and listing
Assets guide — upload files for use in scope
Tools — skip curl with the Go SDK, the chief CLI, or the MCP server
API reference → Chats → Start a chat — full request schema

Get started

Guides

Prerequisites

Start a chat

Poll for the response

Continue the conversation

What you just built

FAQ

Next steps

​Prerequisites

​Start a chat

​Poll for the response

​Continue the conversation

​What you just built

​FAQ

​Next steps

Prerequisites

Start a chat

Poll for the response

Continue the conversation

What you just built

FAQ

Next steps