Rush Cloud API

Run agents from your own code

Start an agent in its own cloud computer from your server, follow it live, steer it, and read what it did. Claude Code, Codex and OpenCode run behind one HTTP API at api.prix.dev.

Base URLhttps://api.prix.devView .md

Quickstart

A key, a session, its live events, a follow-up and the result, in six requests.

Start a session

Every field the dispatch takes: harness, model, effort, persistence and a typed answer.

API reference

22 operations, each with its fields, responses and samples in cURL, TypeScript and Python.

Quickstart

Get a key

An org admin creates a key in the console under Settings → API keys, or with the request beside this step from a signed-in session (rush http sends one for you). The rk_live_… secret is shown once; store it on your server as RUSH_API_KEY.

A key acts as the admin who created it, in its own org, on the session routes. Its runs use Rush's models on that admin's plan, so no Anthropic or OpenAI key is needed. Set expires_at up to a year out, or leave it out for a key that never expires.

Create an API key

curl -X POST "https://api.prix.dev/o/$RUSH_ORG/api-keys" \
  -H "Authorization: Bearer $RUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-runner",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Start a session

A session is one agent run. POST it with an agent and a prompt; the response is the session, already queued or running.

p/_ runs without a repository. Use a Project's handle instead to run in its repository with its connectors. persistence is resumable by default: the sandbox parks with its disk and memory when a turn ends, costs nothing while parked, and a follow-up wakes it where it left off. ephemeral tears it down when the turn ends.

Start a session

curl -X POST "https://api.prix.dev/o/$RUSH_ORG/p/_/sessions" \
  -H "Authorization: Bearer $RUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "claude",
    "prompt": "Summarize the open issues labelled bug in three bullet points.",
    "persistence": "ephemeral"
  }'

Stream its events

Hold the event stream to watch the agent work. Each frame is an event: line and a JSON data: line. The stream closes after done, whose data carries the turn's status and answer. Reconnect with Last-Event-ID to resume where you left off.

Follow a session live

curl -N "https://api.prix.dev/o/$RUSH_ORG/p/_/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $RUSH_API_KEY" \
  -H "Accept: text/event-stream"

Send a follow-up

A follow-up continues the same session. It wakes a parked sandbox, and while a turn is still running it queues and is delivered when the turn ends (202 with its place in the queue).

Send a follow-up

curl -X POST "https://api.prix.dev/o/$RUSH_ORG/p/_/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $RUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Also add a regression test for the timezone case."
  }'

Read the result

The result is the agent's last answer beside the run's status line, its branch and pull request when it opened one. Send output_schema when you start the session and the answer comes back as a typed object in result.structured.

Get the session's answer

curl "https://api.prix.dev/o/$RUSH_ORG/p/_/sessions/$SESSION_ID/result" \
  -H "Authorization: Bearer $RUSH_API_KEY"

Get a webhook when a turn ends

Instead of holding the stream, give the key a public https endpoint. The response carries the whsec_… signing secret once. Every run the key starts then posts run.completed, run.failed or run.cancelled to it within about 30 seconds of a turn ending, signed per Standard Webhooks.

Set, change or remove the key's webhook

curl -X PATCH "https://api.prix.dev/o/$RUSH_ORG/api-keys/$KEY_ID" \
  -H "Authorization: Bearer $RUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://hooks.acme.dev/rush"
  }'

Session lifecycle

A session's status moves left to right. The stream's status events and GET on the session report it; a turn's end also reaches your webhook.

Starting

queued

Accepted; waiting for a run slot.

allocating

Its sandbox is being prepared.

Working

running

The agent is working.

Turn ended

completed

The turn finished with an answer.

paused

A resumable session parked between turns; costs nothing.

input_required

The agent asked a question; send a follow-up.

needs_review

Finished without the proof it was asked for.

A follow-up on a resumable session returns it to running.

Stopped

failed

The run stopped on an error.

cancelled

You cancelled it.

expired

A parked sandbox passed 7 idle days and was removed.

Authentication

Send Authorization: Bearer <token> on every request. The session routes take an org API key or a signed-in session ($RUSH_API_KEY in the samples); every other route takes a signed-in session token (an API key cannot call this route) ($RUSH_TOKEN, as rush http sends it). A missing, revoked or expired token is 401. Another org's resource answers 404, the same as one that does not exist.

Scheme	What it is
`bearerAuth`	An org API key (`rk_live_…`, from POST /o/{org}/api-keys), which acts as the admin who created it, in its own org, on the session routes only; or a signed-in Phoenix ID session, as the console and the `rush` CLI send.

Errors

Every non-2xx body. Two envelopes are live: most routes send error (a sentence) with an optional code or error_code; the org-wide session search sends code and message. Some refusals add fields (candidates, fields, plan usage). Branch on code / error_code.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional

The codes each operation documents, and the status it sends them with:

Code	Status	Sent by
`API_KEY_FIELD_UNSUPPORTED`	422	Start a session
`CATALOG_REFRESH_REQUIRED`	409	Start a session
`COMPUTE_LIMIT_REACHED`	402	Start a session
`CONCURRENCY_LIMIT_REACHED`	409	Cancel, pause, resume, or stop the current turn
`CONTENT_TOO_LARGE`	400	Send a follow-up
`CONTINUATION_UNSUPPORTED`	409	Send a follow-up
`FIELD_UNSUPPORTED_FOR_HARNESS`	422	Start a session
`INSTALLATION_NOT_LINKED`	403	Start a session
`MODEL_UNSUPPORTED`	422	Start a session
`NO_ACTIVE_TURN`	409	Cancel, pause, resume, or stop the current turn
`OUTPUT_SCHEMA_INVALID`	400	Start a session
`PAYMENT_METHOD_REQUIRED`	402	Start a session
`PERSISTENCE_MODE_CONFLICT`	409	Send a follow-up
`PLAN_REQUIRED`	402	Start a session
`QUEUE_FULL`	429	Send a follow-up
`RATE_LIMITED`	429	Start a session
`REPO_NOT_IN_INSTALLATION`	403	Start a session
`SPEND_CAP_REACHED`	402	Start a session
`STOP_TURN_UNCONFIRMED`	422	Cancel, pause, resume, or stop the current turn
`TASK_TERMINAL`	409	Send a follow-up
`TOKEN_LIMIT_REACHED`	402	Start a session
`UNSUPPORTED_AGENT`	422	Start a session
`VALIDATION_ERROR`	400	Create an API key, Set, change or remove the key's webhook
`WEEKLY_COMPUTE_LIMIT_REACHED`	402	Start a session

Limits and concurrency

A key runs at most max_concurrent sessions at once (4 unless you set it when creating the key, up to 100). Starting one more answers 429; wait for a run to end or cancel one.

A running session queues at most 20 follow-ups; one more answers 429 with QUEUE_FULL.

Model usage past what the plan includes continues at the metered rate up to the spend limit an admin sets in Billing; without one it stops with 402.

Pagination

List operations return at most limit rows. When there are more, the response carries next_cursor; pass it back as cursor for the next page, until next_cursor is null. Search the org's sessions, or resolve one by selector, List sessions in one Project, Follow a session live, List a session's tool calls page this way.