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

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

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

Quickstart

Prerequisites

Start a chat

Poll for the response

Continue the conversation

What you just built

Next steps

​Prerequisites

​Start a chat

​Poll for the response

​Continue the conversation

​What you just built

​Next steps

Prerequisites

Start a chat

Poll for the response

Continue the conversation

What you just built

Next steps