# API quickstart

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 URL: `https://api.prix.dev`

## Quickstart

### 1. 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 that admin's own Claude or Codex subscription or API key; with none connected, the first $1 of models is on us. Set `expires_at` up to a year out, or leave it out for a key that never expires.

Reference: [Create an API key](https://getrush.ai/docs/api/create-api-key.md)

```bash
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"
  }'
```

### 2. Start a session

A session is one agent run. `POST` it with a `harness` and an `input`; 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. A run started with a key is resumable: 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.

Reference: [Start a session](https://getrush.ai/docs/api/create-session.md)

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

### 3. 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.

Reference: [Follow a session live](https://getrush.ai/docs/api/stream-session.md)

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

### 4. Send a follow-up

A follow-up continues the same session and wakes a parked sandbox. Send it once the turn has ended: while a turn is still running it is refused with `409 TURN_ACTIVE`, so wait for the session's `status` to leave `running`.

Reference: [Send a follow-up](https://getrush.ai/docs/api/post-session-message.md)

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

### 5. Read the result

The session carries the agent's last answer in `result`, beside its status and the branch and pull request when it opened one.

Reference: [Get one session](https://getrush.ai/docs/api/get-session.md)

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

### 6. 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](https://www.standardwebhooks.com/).

Reference: [Set, change or remove the key's webhook](https://getrush.ai/docs/api/update-api-key-webhook.md)

```bash
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

- 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.)
- 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.)

## Authentication

Send `Authorization: Bearer <token>` on every request.

- `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 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 `message`. Every code: https://getrush.ai/docs/api/errors.md

## 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 take `limit` (integer, default 50, at most 500) and `cursor`: pass the previous response's `next_cursor` to get the next page.

## API reference

Base URL: `https://api.prix.dev`. OpenAPI document: https://getrush.ai/openapi.json

### Sessions

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

- [List sessions](https://getrush.ai/docs/api/list-sessions.md): `GET /o/{org}/sessions`
- [Start a session](https://getrush.ai/docs/api/create-session.md): `POST /o/{org}/sessions`
- [Get one session](https://getrush.ai/docs/api/get-session.md): `GET /o/{org}/sessions/{session}`
- [Cancel a session](https://getrush.ai/docs/api/cancel-session.md): `POST /o/{org}/sessions/{session}/cancel`
- [Start a session (console, by Project)](https://getrush.ai/docs/api/create-project-session.md): `POST /o/{org}/p/{project}/sessions`
- [List the turns of a session](https://getrush.ai/docs/api/list-turns.md): `GET /o/{org}/p/{project}/sessions/{session}/turns`

### Events

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

- [Follow a session live](https://getrush.ai/docs/api/stream-session.md): `GET /o/{org}/sessions/{session}/events`

### Messages

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

- [Read a session's transcript](https://getrush.ai/docs/api/get-session-messages.md): `GET /o/{org}/sessions/{session}/messages`
- [Send a follow-up](https://getrush.ai/docs/api/post-session-message.md): `POST /o/{org}/sessions/{session}/messages`

### Results & artifacts

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

- [Download one artifact](https://getrush.ai/docs/api/get-session-artifact.md): `GET /o/{org}/sessions/{session}/artifacts/{name}`
- [List the files the session's pull request changed](https://getrush.ai/docs/api/get-session-changes.md): `GET /o/{org}/p/{project}/sessions/{session}/changes`
- [List the files a session produced](https://getrush.ai/docs/api/list-session-artifacts.md): `GET /o/{org}/p/{project}/sessions/{session}/artifacts`

### Secrets

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

- [List the org's Project secrets, without values.](https://getrush.ai/docs/api/list-secrets.md): `GET /o/{org}/secrets`
- [Save a secret. The value is sealed and never returned.](https://getrush.ai/docs/api/create-secret.md): `POST /o/{org}/secrets`
- [Replace a secret's value or note.](https://getrush.ai/docs/api/update-secret.md): `PATCH /o/{org}/secrets/{secret}`
- [Delete a secret. A session that names it afterwards fails instead of starting without it.](https://getrush.ai/docs/api/delete-secret.md): `DELETE /o/{org}/secrets/{secret}`

### API keys

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

- [List the org's API keys](https://getrush.ai/docs/api/list-api-keys.md): `GET /o/{org}/api-keys`
- [Create an API key](https://getrush.ai/docs/api/create-api-key.md): `POST /o/{org}/api-keys`
- [Set, change or remove the key's webhook](https://getrush.ai/docs/api/update-api-key-webhook.md): `PATCH /o/{org}/api-keys/{key}`
- [Revoke an API key](https://getrush.ai/docs/api/revoke-api-key.md): `DELETE /o/{org}/api-keys/{key}`
- [Rotate an API key's secret](https://getrush.ai/docs/api/rotate-api-key.md): `POST /o/{org}/api-keys/{key}/rotate`

### Agents & models

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

- [List the harnesses, models and connectors the org can run](https://getrush.ai/docs/api/get-agents-available.md): `GET /o/{org}/agents/available`

### Webhooks

Requests Rush sends to your server.

- [A run started with an API key finished a turn](https://getrush.ai/docs/api/run-finished.md): `webhook`

### Projects

Projects tie a repository to its runs and connectors.

- [List the org's Projects](https://getrush.ai/docs/api/list-projects.md): `GET /o/{org}/p`
- [Get a Project by handle or id](https://getrush.ai/docs/api/get-project.md): `GET /o/{org}/p/{project}`

### GitHub

The GitHub App installations and repositories runs can use.

- [List the GitHub App installations the caller can use and their repositories.](https://getrush.ai/docs/api/get-github-connection.md): `GET /o/{org}/github`

### Saved agents

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

- [List your saved agents, newest first.](https://getrush.ai/docs/api/list-saved-agents.md): `GET /o/{org}/agents`
- [Save an agent.](https://getrush.ai/docs/api/create-saved-agent.md): `POST /o/{org}/agents`
- [Get one of your saved agents.](https://getrush.ai/docs/api/get-saved-agent.md): `GET /o/{org}/agents/{agent}`
- [Edit a saved agent.](https://getrush.ai/docs/api/update-saved-agent.md): `PATCH /o/{org}/agents/{agent}`
- [Delete a saved agent.](https://getrush.ai/docs/api/delete-saved-agent.md): `DELETE /o/{org}/agents/{agent}`

### Attachments

Files uploaded to attach to a run.

- [Download one file the session was given](https://getrush.ai/docs/api/get-session-attachment.md): `GET /o/{org}/sessions/{session}/attachments/{id}`
- [Get an upload URL for each file of a session's input.](https://getrush.ai/docs/api/create-files.md): `POST /o/{org}/files`