Quickstart

1. Create an API key

Open Settings → API Keys and click New key. Copy the value — we only show it once. Keys look like:

cr_live_a1b2c3d4e5f6...

Store keys in your secret manager — they grant full ingestion access for your workspace.

2. Register an agent

Either use the UI — Agents → fill the Register new agent form — or create one by API:

curl -X POST "$BASE_URL/api/agents" \
  -H "Authorization: Bearer cr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Classifier",
    "model": "gpt-4o",
    "description": "Routes inbound tickets",
    "tags": ["prod", "customer-support"]
  }'

Copy the agent.idUUID from the response — you'll pass it to /api/runs/start below.

3. Start a run

curl -X POST "$BASE_URL/api/runs/start" \
  -H "Authorization: Bearer cr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_uuid>",
    "model": "gpt-4o"
  }'

Response: { "run_id": "..." }

4. Append steps

curl -X POST "$BASE_URL/api/runs/$RUN_ID/step" \
  -H "Authorization: Bearer cr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "search_docs",
    "reasoning": "User asked about pricing tiers",
    "result": "Returned 3 matching pages",
    "decision": "respond_with_summary"
  }'

5. Close the run

curl -X POST "$BASE_URL/api/runs/$RUN_ID/end" \
  -H "Authorization: Bearer cr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "tokens_input": 312,
    "tokens_output": 218,
    "cost_usd": 0.0042
  }'

Refresh Runs — your run will appear with timeline, cost, and status.