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

# Quickstart

> Send your first Chief API request in minutes.

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](/api-reference/introduction).

<Note>
  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](/ai-native). This page is the
  manual, do-it-yourself path.
</Note>

## Prerequisites

* [A Chief account](https://chief.bot/auth/signup) with access to a project
* A PAT from [**Settings → API tokens**](https://chief.bot/settings/tokens)
* Your project id (`project_…`)

Export variables for the examples:

```bash theme={null}
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:

```bash theme={null}
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`):

```json theme={null}
{
  "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:

```bash theme={null}
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"
```

<Tip>
  Use exponential backoff between polls and cap total wait time in production.
</Tip>

## Continue the conversation

```bash theme={null}
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](/what-you-can-build) for where
to take it.

## Next steps

* [What you can build](/what-you-can-build) — concrete outcomes built on this loop
* [Chats guide](/guides/chats) — scope, intelligence modes, and listing
* [Assets guide](/guides/assets) — upload files for use in `scope`
* [Tools](/tools) — skip curl with the Go SDK, the `chief` CLI, or the MCP server
* **API reference → Chats → Start a chat** — full request schema