API quickstart
This page takes you from nothing to a thread you can watch working at capy.ai. Everything is copy-paste curl; the only prerequisites are a Capy account with a project set up and a terminal.
1. Mint an API key
API settings creates organization-scoped keys. The plaintext appears only once. Copy it then; you can only revoke and replace it later.


Export the key in your terminal:
export CAPY_API_KEY="capy_..."2. Find your project id
Threads live in projects. List the projects your key can access and pick one — this also verifies the key:
curl -H "Authorization: Bearer $CAPY_API_KEY" \
"https://api.capy.ai/api/v1/projects"export PROJECT_ID="project_..."Newly created projects use project_... ids; imported ones keep their original id.
A capy/Unauthorized here means the key is wrong or revoked; later calls answer capy/ProjectNotFound when a project id is wrong or the project isn't reachable from this key's organization.
3. Create a thread
requestId is an idempotency token you mint: retries with the same id return the same thread instead of starting a second billable run.
curl -X POST "https://api.capy.ai/api/v1/threads" \
-H "Authorization: Bearer $CAPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"requestId": "'"$(uuidgen)"'",
"projectId": "'"$PROJECT_ID"'",
"message": "Fix the flaky retry test in packages/queue and open a PR."
}'The response is the Thread projection, the same shape every thread read returns:
{
"id": "jam_01...",
"projectId": "project_...",
"title": null,
"status": "working",
"archived": false,
"usage": { "llmCredits": 0, "imageCredits": 0, "vmCredits": 0, "totalCredits": 0 },
...
}Save the id:
export THREAD_ID="jam_01..."For an hours-long job, include instructions in message to run a background command with an explicit timeout and wait for it. See long-running jobs for the 6-hour command limit, keep-awake behavior, and billing.
4. Poll the status
curl -H "Authorization: Bearer $CAPY_API_KEY" \
"https://api.capy.ai/api/v1/threads/$THREAD_ID"status is what you poll on:
| Status | Meaning |
|---|---|
working | The agent is running now |
waiting | The agent paused and resumes by itself when something it waits on arrives, such as CI results, a timer, or a subagent finishing |
idle | The agent stopped and waits for your next message. Its last reply holds the result or a question for you |
failed | The last run ended with an error. The transcript shows how far it got |
archived | The thread is archived. POST /threads/{threadId}/unarchive restores it |
Poll every few seconds while the status is working. Any other status means the agent stopped: idle and failed wait for you, and waiting resumes on its own, so poll again later for its next result. Right after a create or a reply, a thread can read idle for a moment before the agent picks up the message, so wait a few seconds before the first poll. Threads run for minutes, not seconds. A real coding task takes as long as the work does.
5. Read the messages
curl -H "Authorization: Bearer $CAPY_API_KEY" \
"https://api.capy.ai/api/v1/threads/$THREAD_ID/messages"The transcript is { items, cursor, beforeCursor } of Message entries: your messages (source: "user"), the agent's replies (source: "assistant"), and one-line tool activity (source: "tool" with the tool name, never raw arguments or results). When the agent opens a pull request, the PR link arrives in its assistant reply text.
Page forward by passing the response's cursor back as after; poll the same way to tail a live thread, or hold one connection open with the stream and let the entries arrive as they commit.
6. Reply
curl -X POST "https://api.capy.ai/api/v1/threads/$THREAD_ID/message" \
-H "Authorization: Bearer $CAPY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Also update the changelog."}'The response is an admit receipt, { "id": "...", "deduped": false }: the message landed and the agent wakes. By default a message interrupts what the agent is doing; pass "delivery": "queue" to wait for the current work to finish first.
You're done
Open capy.ai: the thread you just created is on the Threads page, transcript and all, exactly as the API reported it. Everything the app shows rides the same platform you just drove with curl.
Next: common flows for the task tree, reviews, and automation webhooks.