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

In the app, go to Settings → API and create a key. The plaintext is shown exactly once (there’s no re-display, only revoke-and-remint), so export it now:

export CAPY_API_KEY="capy_..."

2. Find your project id

Threads live in projects, and the public API has no projects endpoint yet, so the id comes from the app: open any of your project’s pages and copy the whole route parameter after /project/ in the URL. Newly created projects use project_... ids; imported ones keep their original id.

export PROJECT_ID="..."

Verify the key and the project together by listing threads; an empty page is a working setup:

curl -H "Authorization: Bearer $CAPY_API_KEY" \
  "https://api.capy.ai/api/v1/threads?projectId=$PROJECT_ID"

A capy/Unauthorized means the key is wrong or revoked; a capy/ProjectNotFound means the 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": "proj_...",
  "title": null,
  "status": "active",
  "archived": false,
  "usage": { "llmCredits": 0, "vmCredits": 0, "totalCredits": 0 },
  ...
}

Save the id:

export THREAD_ID="jam_01..."

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
`active`	The agent is working
`waiting`	Waiting on something external: CI, a timer, a callback
`pending_user`	Blocked on your input; read the messages and reply
`ready_for_review`	Work delivered, awaiting your review
`idle`	At rest
`error`	The run failed
`archived`	Archived

Poll every few seconds until the status leaves active and waiting. 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 } 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.

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.

​1. Mint an API key

​2. Find your project id

​3. Create a thread

​4. Poll the status

​5. Read the messages

​6. Reply

​You’re done