Ultrac docs.

Create keys on the API keys page once your account is approved. A key looks like ultrac_sk_ followed by 43 characters; it is shown once, stored only as a hash, and can be revoked at any time - revoked keys answer 401 on the very next request. Up to ten active keys per account, so each app or machine can have its own.

Keys are not for browsers: the API sets no CORS headers and reads no cookies. Send them from servers, scripts, the CLI and the desktop app.

ultrac login asks for a key, checks it against /v1/models, and keeps it in ~/.ultrac/auth.json. After that, ultrac keeps agent work local by default: preflight the worktree, capture the working context, plan the checks, save the report, then pick a mode that matches the task.

# Sign the CLI in with the key you created on this page.
ultrac login --base-url https://ultrac.io/v1

# Paste the key when asked. It is checked against https://ultrac.io/v1/models
# and kept in ~/.ultrac/auth.json - never in the repository you run it from.

Send ordered messages to POST /v1/chat/completions. The reply is OpenAI's chat.completion object, or with stream: true the same server-sent chat.completion.chunk events OpenAI sends, ending in data: [DONE].

curl -N https://ultrac.io/v1/chat/completions \
  -H "Authorization: Bearer $ULTRAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cosmic-1",
    "stream": true,
    "messages": [{"role": "user", "content": "Analyze this incident."}]
  }'

One request, one reply: a completion has to finish before the connection does, streaming or not. Work that runs for minutes - an agent loop, a long review - belongs in a task instead, which you can disconnect from and rejoin: see Long-running tasks.

The cheapest authenticated call: lists the one served model in OpenAI's list shape. The CLI uses it to check a key on login, and it answers even when the model host is down, because "is this key good" is a different question from "is the model up".

curl https://ultrac.io/v1/models \
  -H "Authorization: Bearer $ULTRAC_API_KEY"

A completion has to finish inside one request, and a task that takes minutes cannot: functions are capped, laptops sleep, tabs close, and each time the model's work goes with the connection. So a task is a record and a log rather than a request. POST /v1/runs answers 202 with the run before any model work starts, a worker beside the model does the work and appends events as it goes, and you read those events as server-sent events - live, later, or from wherever you dropped. Disconnecting costs nothing: the task keeps running and every event waits in the log, which is kept for 30 days. The dashboard's Tasks page is these same five endpoints behind a cookie.

Every one takes the same bearer key as the rest of /v1, and every one is scoped to the key's account: another account's id answers 404, the same as an id that never existed, so ids cannot be probed.

The body is { "prompt": "..." } - one user turn - or { "messages": [...] } in the shape chat completions takes; send both and the prompt becomes the newest turn. An optional chatId your account owns attaches the finished turn to that dashboard chat. Messages are trimmed to the model window at creation and stored trimmed, so the input you get back is exactly what the model will be given. There is no stream field and no tools field: a task always streams into its log, and the worker sends no tools.

A run on the wire is { id, object: "run", status, source, model, chatId, title, createdAt, startedAt, finishedAt, attempt, lastSeq, cancelRequested, error, input, output }. title is the first line of the newest user message, and lastSeq is the id of the newest event, which is where a stream resumes from.

The event stream is plain server-sent events. The first line is retry: 1000, then one block per stored event in seq order: id: <seq>, event: <type>, data: <json>, blank line.

Each id is that event's seq, and seq is ordered per run, so rejoining is exact: reconnect with Last-Event-ID: <the last id you saw> and you get what you missed and nothing twice. A browser EventSource sends that header by itself; every other client sets it, or passes ?since=<seq>. The header wins when both are there, because it names what the client actually received. ?since=0 replays the whole log, which is what to trust when rebuilding the text from scratch.

A comment line (: keep-alive) goes out after 15 seconds of silence so proxies hold the connection open. The connection itself is capped at 55 seconds, under the 60-second function limit: the stream ends cleanly on purpose rather than being killed mid-write, so treat a clean end as normal and reconnect - only a terminal event means the task is over. If a task ended without a terminal event ever reaching its log, the stream notices from the run's own status and closes with a synthetic status event (synthetic: true) whose id repeats the last real seq, so no client waits forever.

An account may have 3 tasks queued or running at once; a task holds a worker for as long as the model takes, and the workers sit beside one GPU. The next create answers 429 too_many_active_runs, whose message names how many are active and what the limit is - wait for one to finish, or cancel one. That is separate from the rate limits above: creating a task also counts against the plan's per-minute and per-day allowances like a completion, and going over those is the usual 429 rate_limit_exceeded with retry-after. Reading, streaming and cancelling count per minute only.

Cancelling is immediate only while a task is queued: there is no worker to ask, so it is cancelled on the spot and the answer is 200 with outcome: "cancelled". On a running task the flag is set and the answer is 202 with outcome: "requested"; the worker reads the flag every two seconds, stops the model, writes a status: cancelled event carrying the partial text, and finishes the task with that text as its output. So 202 means asked, and the stream is what tells you it stopped. A task that had already finished answers 409 run_already_finished; cancelling one that is already cancelling is harmless.

# 1. Queue the task. The answer is 202 with the run, before any model work starts.
curl -s https://ultrac.io/v1/runs \
  -H "Authorization: Bearer $ULTRAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Audit this incident timeline and list what is missing."}'
# {"id":"6f1a...","object":"run","status":"queued","attempt":0,"lastSeq":0,...}

RUN=6f1a...   # the id from step 1

# 2. Follow it. -N keeps curl from buffering, so events print as they are written.
curl -N https://ultrac.io/v1/runs/$RUN/events \
  -H "Authorization: Bearer $ULTRAC_API_KEY"
# retry: 1000
#
# id: 1
# event: status
# data: {"status":"running","attempt":1}
#
# id: 2
# event: delta
# data: {"text":"The timeline is missing "}
#
# : keep-alive
#
# id: 7
# event: done
# data: {"text":"...","finish_reason":"stop","usage":{...}}

# 3. The connection is capped at 55 s. If the task is still going when it ends,
#    reopen with the last id you saw: you get what you missed and nothing twice.
curl -N https://ultrac.io/v1/runs/$RUN/events \
  -H "Authorization: Bearer $ULTRAC_API_KEY" \
  -H "Last-Event-ID: 7"

# Polling works too, if a stream is awkward: the run carries its status, and
# once it is over, the whole output.
curl -s https://ultrac.io/v1/runs/$RUN \
  -H "Authorization: Bearer $ULTRAC_API_KEY"

# Stop it early: 200 cancelled while still queued, 202 requested once a worker
# has it, 409 if it had already finished.
curl -s -X POST https://ultrac.io/v1/runs/$RUN/cancel \
  -H "Authorization: Bearer $ULTRAC_API_KEY"

Every account has a per-minute and a per-day allowance from the plan confirmed on it; until a plan is confirmed, Free applies whichever plan was chosen. Every key has its own per-minute bucket at the account's figure, so a 429 names the key that is hot and ten keys cannot multiply the plan. Over the limit answers 429 with retry-after; every reply carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset for the window you are closest to. Nothing is billed.

Every error body is { error: { message, type, param, code } }. SDKs map the status to the exception they already have; code is the stable thing to branch on.

{
  "error": {
    "message": "Incorrect API key provided. Check the key, or create a new one at /keys.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}