Starts one agent run in a fresh sandbox and returns it at once with
202; follow it with GET …/events or the key's webhook. It runs in the
repository a resources URL names, or in none.
Started with an API key (or through the MCP server, or of an agent made from a
template), the run always uses Rush's models, billed per token to the key's
creator: past the account's one-time $1 free credit, paid from
the creator's prepaid credits, and refused at $0. It never uses a connected account of the
creator's, and account_id is refused 422 ACCOUNT_UNSUPPORTED. A key runs at most max_concurrent runs
at once (default 4), within its creator's plan limit; a run past either is answered 202 with
status: queued and starts, oldest first, when a slot frees; a key at its own limit holds up
only its own runs, not the creator's other keys or console runs. When agent
is a saved agent's id or exact name the run uses that saved agent, and gets exactly the connections it names
plus those the run names in connections. A key run's repository is
reached through its creator's GitHub App installations, and a Linear
issue through its creator's Linear connection.
Authenticate with an API key or a signed-in session.
Path parameters
The org's slug or id. A caller with no role in the org gets 404.
Headers
Send request_id in the body instead. Read the same way until it is removed; a
request_id in the body wins.
Request body
agent is required, and the repository, if any, is a resources URL. Any
other field is 400 UNKNOWN_FIELD; name, metadata, output_schema,
harness, agent_id and profile_id are 400 FIELD_REMOVED.
What runs: a harness (claude, codex or opencode), or a saved agent's id or exact name (GET /o/{org}/agents; a harness name keeps its meaning, and a name two agents share is 422 INVALID_BODY), which brings its harness, model, effort, instructions, skills and connections; one whose saved setup the catalog no longer supports (such as skills with a tool selection that leaves out Skill) is 422 UNSUPPORTED_PROFILE, with fields naming the choice, until it is edited (one added from Community, until its maker lists a new revision). Required on POST /o/{org}/sessions; on a Project's route the Project's default harness runs when it is left out.
The task, as a string or as content blocks. Text blocks are joined, with a blank line
between them, into the prompt (at most 256 KiB, at least one text block). Every file
block is stored before the run starts and downloaded into the sandbox at
/workspace/.rush/attachments/, where the prompt names it.
A model id that GET /o/{org}/agents/available lists for this harness. Omitted: the harness default.
Reasoning effort; must be one the model's row lists.
noneminimallowmediumhighxhighmaxautoHow fast the model runs. A run on Rush's models (every API key's, and a person's on the model trial) runs at standard only; fast is 422 MODEL_UNSUPPORTED (400 VALIDATION_ERROR on opencode, 422 SPEED_NOT_QUALIFIED on a saved agent). Omitted: standard.
standardfastRefused 422 ACCOUNT_UNSUPPORTED with an API key: a developer run always uses Rush's models. Only a person's own run, started in the console, may name one of their connected accounts.
Rush's models, covered by the account's one-time $1 and then paid from the caller's prepaid credits. Every run started with an API key or an MCP client already uses them, so this changes nothing there; a person's own run that sends it is refused 422 ACCOUNT_UNSUPPORTED.
platformA UUID you make once for each run you mean to start. A retry with the same request_id and
body returns the run it first started, until that run fails or is cancelled; the same
request_id with another body or Project is 409 IDEMPOTENCY_CONFLICT. Not a UUID is
400 VALIDATION_ERROR. Optional: without one, every request starts a run.
Skills the agent loads for this run, each by public URL, as a string or {url}: a GitHub tree URL to a
directory holding SKILL.md, a URL to a SKILL.md file (github.com/…/blob/…,
raw.githubusercontent.com/… or any https host), or a .zip URL. Fetched when the run
is created; a GitHub source is pinned to the commit its branch or tag points at, and the
pin is kept with the run. All of a run's skills pack to at most
96 KiB compressed. An unreachable URL is 422 SKILL_FETCH_FAILED; no SKILL.md, a bad
name or too large is 422 SKILL_INVALID.
1 item fields
What this run connects to, each entry in one of three forms:
- An id of one of the caller's own connections (
GET /me/connections): an MCP server (connected with a token, by OAuth, or with no auth), a Google or Microsoft product (Gmail, Outlook, OneDrive, ...) of one account, or a GitLab account. Secrets are never named: a session gets every secret of its Project (/o/{org}/secrets). - A name of one of them, the
nameGET /me/connectionslists: the name the caller gave an MCP server ("deepwiki","EXA_API_KEY"), or the provider of an account or a built-in connector, whichGET /me/connectionslists as{type: "app", name: "linear"}("linear","gmail"). Only the caller's own rows match, and only user-level ones or ones in this run's Project. A name that matches two of them is422 CONNECTION_AMBIGUOUS, whose message lists their ids; send one id instead. - An inline MCP server
{url, name?, auth?}, used by this run and its follow-ups only and never added to/me/connections.urlis a streamable HTTP endpoint on https whose host resolves to public addresses only (else422 MCP_SERVER_URL_INVALID).authis the shapePOST /me/connectionstakes:{mode: "bearer", token}sends the token asAuthorization: Bearer;{mode: "none"}or noauthsends none. Atokenbesideurlis400 FIELD_REMOVED. The token is stored encrypted on the run and never returned.namedefaults to a slug of the host (mcp-deepwiki-com), and may not be a built-in connection's or share a name with another entry (422 CONNECTION_AMBIGUOUSwhen it matches a named server).
Ids and names fit Anthropic's stored-credential model (a vault id per run); the inline
form fits OpenAI's inline authorization and Cursor's mcpServers headers. An id or
name that is unknown, still connecting, or waiting on a reconnect is
422 CONNECTION_NOT_READY. Follow-ups keep all three.
3 item fields
1 fields
Your own linked computers this run may drive, by name from GET /me/devices. The agent
reaches each one's signed-in browser with browser start --device NAME; every step runs on
that computer only after you approve the run there, in the Rush menu-bar app. A device
that is not yours is 404 NOT_FOUND; one whose app is not connected is 409 DEVICE_OFFLINE.
Follow-ups keep them. An API key names its creator's devices.
What Rush puts in front of the agent before it starts, each by URL, with connection
naming the account that reaches it when more than one could:
https://github.com/<owner>/<repo> clones the repository at its default branch, …/tree/<branch>
at that branch, and …/pull/<n> on that open pull request's branch; at most one
repository per run, reached through a GitHub App installation of the caller
(connection is an installation id from GET /o/{org}/github).
https://gitlab.com/<group>/<project> (…/-/tree/<branch> at a branch) clones a gitlab.com
project with the caller's own GitLab sign-in (connection is its id). On a Project run it may
only name the Project's repository; a Project whose repository is on gitlab.com clones it on
every run with the starter's own GitLab sign-in, refused like a gitlab.com resource when they
have none (422 CONNECTION_NOT_READY). https://linear.app/<workspace>/issue/<ID> puts the
issue in the prompt, read through the caller's Linear connection. Any other URL is
422 RESOURCE_UNSUPPORTED; a repository no installation covers, or an issue with no
Linear connection, is 422 RESOURCE_NOT_ACCESSIBLE.
2 item fields
Responses
202The session as GET reads it, answered once it is saved, so usually queued (allocating when its start already began).
The session id.
The org as the request's path named it.
The Project the console ran the session in.
paused is a resumable session parked between turns; needs_review finished without the proof it was asked for; cancelling appears only in the 202 answer to a cancel whose sandbox is still being released; GET reads cancelled once it is.
queuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancellingcancelledexpiredclaude, codex or opencode.
The saved agent the session was started from, if any.
The agent's final answer for the last finished turn, in full.
Only on a follow-up's answer: the turn the message opened, running or waiting in line (queued).
2 fields
runningqueuedWhat the last finished turn did, written from result when it finished: the line Rush's notifications lead with. Absent when the turn left no answer.
2 fields
Why a failed or expired run ended. message is a sentence a person can act on.
2 fields
A plan or account limit the run hit (FREE_TRIAL_USED, PLAN_REQUIRED, TOKEN_LIMIT_REACHED, CREDITS_EXHAUSTED, SPEND_CAP_REACHED, COMPUTE_LIMIT_REACHED, WEEKLY_COMPUTE_LIMIT_REACHED, PAYMENT_METHOD_REQUIRED), the model account it used (PROVIDER_AUTH_FAILED, PROVIDER_RATE_LIMITED, MODEL_ACCOUNT_MISSING), how it ended (HARNESS_EXITED, RUN_STALLED, RUN_TIMED_OUT, RUN_START_FAILED, MACHINE_UNAVAILABLE, MACHINE_REFUSED, MACHINE_LOST, LEASE_EXPIRED, SAVED_STATE_EXPIRED, BRANCH_NOT_FOUND, AGENT_UNAVAILABLE, CONNECTION_UNAVAILABLE, AUTH_FAILED), or RUN_FAILED. Runs that failed before codes were recorded read RUN_FAILED.
Uncached input plus cache writes plus output.
Every file the agent saved to /workspace/.rush/artifacts/. url downloads it from this
API with no credential until url_expires_at, an hour after the read; read the session
again for a fresh link. GET …/artifacts/{name} with the key also downloads it.
4 item fields
A signed https link to the file on this API.
The files the session was started or followed up with. url downloads one with no
credential until url_expires_at, as for artifacts; GET …/attachments/{id} with the
key also downloads it.
5 item fields
A signed https link to the file on this API.
The connections the session's tokens acted as, one entry per account however often it
was used, with when it was first used: a signed-in app account (oauth) or an MCP server
signed as one person (mcp); a connection added to the Project for its members is not
listed, so its sessions stay readable by the team. The session's agent_id
says whose agent it was. Absent when the session used none, and for sessions started
before accounts were recorded. Never a token.
5 item fields
oauthmcpFor oauth the app vendor (google, microsoft, buffer, quickbooks); for mcp the server's name.
For oauth the account's email (for QuickBooks, the company's realm id); for mcp the connection's id, or the server's host when the session supplied its own token.
The account's products the session reached, such as gmail or outlook. Absent for mcp.
400The body is invalid: no input or no text block in it, a malformed input block, no agent, an unknown effort, speed or persistence, speed: fast on opencode, a malformed skills, connections or resources entry, two repositories, or a request_id that is not a UUID.
The body is invalid: no input or no text block in it, a malformed
input block, no agent, an unknown effort, speed or
persistence, speed: fast on opencode, a malformed skills, connections or resources
entry, two repositories, or a request_id that is not a UUID. A
field this route does not take is UNKNOWN_FIELD. A base64 file whose bytes
are not its media_type, or an image block whose file is not an
image, is INVALID_BODY. A body that still sends a removed field is
FIELD_REMOVED, whose message names its replacement: prompt and
attachments became input; repos, installation_id, repo_owner,
repo_name, base_branch, on_pr and sources became resources;
mcp_servers became an inline {url, name?, auth?} entry in connections,
whose own token became auth: {mode: bearer, token};
harness, agent_id and profile_id became agent;
agents_repo became a Project Skill or skills;
name, metadata and output_schema are not taken.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
402The plan does not cover this run.
The plan does not cover this run. An API key or MCP run: TOKEN_LIMIT_REACHED (the account's
one-time $1 is used and it has no credits; a model call mid-run answers the same),
CREDITS_EXHAUSTED (bought credits are used up) or SPEND_CAP_REACHED. A person's own run:
FREE_TRIAL_USED (the Free plan's $1 is used), PLAN_REQUIRED (an automation or Slack run on Free,
or an account with no Free plan), MODEL_ACCOUNT_MISSING (a paid plan's run uses the person's own
model account), COMPUTE_LIMIT_REACHED or WEEKLY_COMPUTE_LIMIT_REACHED. Either: PAYMENT_METHOD_REQUIRED.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
403The Project's repository is not in a GitHub App installation linked to the caller (INSTALLATION_NOT_LINKED, REPO_NOT_IN_INSTALLATION).
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
404The Project, or a file_id in input, is not found (ATTACHMENT_NOT_FOUND).
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
409The request_id (or the deprecated Idempotency-Key) was first sent with a different body or Project (IDEMPOTENCY_CONFLICT), the repository's GitHub App installation is suspended, a pull-request resource names one that is not open, a saved agent's catalog changed since it was reviewed (CATALOG_REFRESH_REQUIRED), a file_id already belongs to another run (ATTACHMENT_IN_USE), or a file_id was never PUT to its upload_url (ATTACHMENT_NOT_UPLOADED).
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
410A file_id's stored bytes have expired (ATTACHMENT_EXPIRED).
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
413The request body is over 32 MB (REQUEST_TOO_LARGE).
The request body is over 32 MB (REQUEST_TOO_LARGE). Send a large file as a url
source, or upload it with POST /o/{org}/files and send a file source.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
422A field the run cannot honor: an agent outside claude, codex, opencode (UNSUPPORTED_AGENT); a model the harness does not list in GET /o/{org}/agents/available, or speed: fast on claude or codex for a run on Rush's models (an API key's, or a person's on the model trial), which run at standard speed (code MODEL_UNSUPPORTED; on a saved agent SPEED_NOT_QUALIFIED); a url source that could not be fetched (INPUT_FETCH_FAILED: not https, a private address, more than 3 redirects, a non-2xx answer, more than 60 seconds, or an image block answered with something else); a skill URL that cannot be fetched (SKILL_FETCH_FAILED) or holds no valid SKILL.md (SKILL_INVALID); a connection id or name that is not one of the caller's connected connections, or a GitLab account (CONNECTION_NOT_READY); a name that matches two of them, or an inline server named like a named one (CONNECTION_AMBIGUOUS); an inline MCP server whose host is not public (MCP_SERVER_URL_INVALID); a resource URL Rush cannot attach (RESOURCE_UNSUPPORTED); or a repository no GitHub App installation of the caller covers, or a Linear issue with no Linear connection to read it (RESOURCE_NOT_ACCESSIBLE); or account_id, since a developer run always uses Rush's models (ACCOUNT_UNSUPPORTED); a saved agent whose setup the catalog no longer supports (UNSUPPORTED_PROFILE, with fields naming each choice as a save does); or a saved agent that keeps its runtime current in a Project pinned to a partial release that does not hold the harness's cli_version (RUNTIME_UNPINNABLE).
A field the run cannot honor: an agent outside claude, codex,
opencode (UNSUPPORTED_AGENT); a model the harness does not list
in GET /o/{org}/agents/available, or speed: fast on claude or codex for a run on Rush's models
(an API key's, or a person's on the model trial), which run at standard speed (code MODEL_UNSUPPORTED; on a saved agent SPEED_NOT_QUALIFIED); a url
source that could not be fetched (INPUT_FETCH_FAILED: not https, a
private address, more than 3 redirects, a non-2xx answer, more than 60
seconds, or an image block answered with something else); a skill
URL that cannot be fetched (SKILL_FETCH_FAILED) or holds no valid
SKILL.md (SKILL_INVALID); a connection id or name that is not one of the
caller's connected connections, or a GitLab account (CONNECTION_NOT_READY); a
name that matches two of them, or an inline server named like a named one
(CONNECTION_AMBIGUOUS); an inline MCP server whose host is not public
(MCP_SERVER_URL_INVALID);
a resource URL Rush cannot attach (RESOURCE_UNSUPPORTED); or a
repository no GitHub App installation of the caller covers, or a Linear
issue with no Linear connection to read it (RESOURCE_NOT_ACCESSIBLE);
or account_id, since a developer run always uses Rush's models
(ACCOUNT_UNSUPPORTED); a saved agent whose setup the catalog no longer
supports (UNSUPPORTED_PROFILE, with fields naming each choice as a save
does); or a saved agent that keeps its runtime current in a Project pinned
to a partial release that does not hold the harness's cli_version
(RUNTIME_UNPINNABLE). The run is not created.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
429The account is over its 1,800-a-minute request budget (RATE_LIMITED).
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.