API reference

Every request your server can send to https://api.phoenix.so, and the one Rush sends back to you. Generated from the OpenAPI document the API is checked against; download it as openapi.json.

View .md

Sessions

Start, list, read and steer sessions. A session is one agent run in its own sandbox.

Events

Follow a session live over server-sent events, or read its log.

Messages

Read a session's transcript and tool calls, and send it follow-ups.

Results & artifacts

The answer, changed files, captured transcript and files a session produced.

Secrets

Values a session uses without them appearing in a response. Every secret belongs to one Project and reaches every session in it.

API keys

API keys for server-to-server calls, and the webhook each key delivers to.

Agents & models

The harnesses, models, apps and MCP servers an org can run.

Webhooks

Requests Rush sends to your server.

Projects

Projects tie a repository to its runs and connectors.

Billing

The caller's plan, usage, spend limit and Stripe sessions.

GitHub

The GitHub App installations and repositories runs can use.

Saved agents

Reusable agent setups (harness, model, tools and connections), revisioned.

Attachments

Files uploaded to attach to a run.

Devices

Your own computers, which a run you start can use with your approval.

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.
cancelling
You cancelled it; its sandbox is still being released.
cancelled
You cancelled it.
expired
A parked sandbox passed 7 idle days and was removed.
A session moves from queued and allocating to running, then ends its turn or stops.

Authentication

Send Authorization: Bearer <token> on every request. The session routes take an 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, a person's signed-in console session). A missing, revoked or expired token is 401. Another org's resource answers 404, the same as one that does not exist.

SchemeWhat it is
bearerAuth

An API key (rk_live_…, from POST /o/{org}/api-keys), which acts as the member who created it, in its own org, on the routes marked x-audience: public; or a signed-in Phoenix ID session, as the console and the rush CLI send.

Errors

Every error is JSON with a stable code and a readable message. Every code, its status and the operations that send it.

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). One more is created queued and starts, oldest first, when one of the key's slots frees (a parked sandbox holds none); it never holds up your other keys or the console.

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

Past your account's first $1, a key's runs on Rush's models are paid from prepaid credits, and stop with 402 at $0. A spend limit set in Billing caps how much of the credits they use in a period.

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. List sessions, Follow a session live, List saved agents you can use, newest first., List the agents companies listed in Community, List Community agents, with no credential page this way.

limitintegerqueryoptional

Max rows to return.

Default 50min 1max 500
cursorstringqueryoptional

Opaque pagination cursor from a previous response's next_cursor.