Start a session

POST/o/{org}/sessions
View .md

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

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

Headers

idempotency-keystringoptional

Send request_id in the body instead. Read the same way until it is removed; a request_id in the body wins.

at most 128 characters

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.

agentstringoptional

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.

inputstring | array of object | objectrequired

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.

modelstringoptional

A model id that GET /o/{org}/agents/available lists for this harness. Omitted: the harness default.

effortstringoptional

Reasoning effort; must be one the model's row lists.

One ofnoneminimallowmediumhighxhighmaxauto
speedstringoptional

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

One ofstandardfast
account_idstringoptional

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

strategystringoptional

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.

One ofplatform
request_idstringoptional

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

skillsarray of string | objectoptional

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
urlstringrequired
Format uriat most 2048 characters
connectionsarray of string | objectoptional

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 name GET /me/connections lists: the name the caller gave an MCP server ("deepwiki", "EXA_API_KEY"), or the provider of an account or a built-in connector, which GET /me/connections lists 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 is 422 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. url is a streamable HTTP endpoint on https whose host resolves to public addresses only (else 422 MCP_SERVER_URL_INVALID). auth is the shape POST /me/connections takes: {mode: "bearer", token} sends the token as Authorization: Bearer; {mode: "none"} or no auth sends none. A token beside url is 400 FIELD_REMOVED. The token is stored encrypted on the run and never returned. name defaults 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_AMBIGUOUS when 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
urlstringrequired
Format uriat most 2048 characters
namestringoptional
authobject | objectoptional
1 fields
modestringrequired
devicesarray of stringoptional

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.

resourcesarray of objectoptional

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
urlstringrequired
Format uriat most 2048 characters
connectionstringoptional
at most 64 characters

Responses

202The session as GET reads it, answered once it is saved, so usually queued (allocating when its start already began).
execution_idstringrequired

The session id.

org_idstringrequired

The org as the request's path named it.

project_idstringoptional

The Project the console ran the session in.

Format uuid
statusstringrequired

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.

One ofqueuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancellingcancelledexpired
harnessstringoptional

claude, codex or opencode.

agent_idstringoptional

The saved agent the session was started from, if any.

Format uuid
modelstringoptional
effortstringoptional
resultstringoptional

The agent's final answer for the last finished turn, in full.

turnobjectoptional

Only on a follow-up's answer: the turn the message opened, running or waiting in line (queued).

2 fields
idstringrequired
Format uuid
statusstringrequired
One ofrunningqueued
recapobjectoptional

What 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
headlinestringrequired
at most 80 characters
pointsarray of stringoptional
errorobjectoptional

Why a failed or expired run ended. message is a sentence a person can act on.

2 fields
codestringrequired

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.

messagestringrequired
repo_ownerstringoptional
repo_namestringoptional
branchstringoptional
pr_urlstringoptional
input_tokensintegeroptional
output_tokensintegeroptional
cache_read_tokensintegeroptional
cache_write_tokensintegeroptional
total_tokensintegeroptional

Uncached input plus cache writes plus output.

reasoning_tokensintegeroptional
total_cost_usdnumberoptional
tool_calls_countintegeroptional
turns_countintegeroptional
artifactsarray of objectoptional

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
namestringrequired
mime_typestringrequired
urlstringrequired

A signed https link to the file on this API.

Format uri
url_expires_atstringrequired
Format date-time
attachmentsarray of objectoptional

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
idstringrequired
Format uuid
namestringrequired
mime_typestringrequired
urlstringrequired

A signed https link to the file on this API.

Format uri
url_expires_atstringrequired
Format date-time
accountsarray of objectoptional

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
kindstringrequired
One ofoauthmcp
vendorstringrequired

For oauth the app vendor (google, microsoft, buffer, quickbooks); for mcp the server's name.

accountstringrequired

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.

productsarray of stringoptional

The account's products the session reached, such as gmail or outlook. Absent for mcp.

first_used_atstringrequired
Format date-time
created_atstringoptional
Format date-time
completed_atstringoptional
Format date-time
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.

errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
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.

errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
403The Project's repository is not in a GitHub App installation linked to the caller (INSTALLATION_NOT_LINKED, REPO_NOT_IN_INSTALLATION).
errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404The Project, or a file_id in input, is not found (ATTACHMENT_NOT_FOUND).
errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
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).
errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
410A file_id's stored bytes have expired (ATTACHMENT_EXPIRED).
errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
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.

errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
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.

errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The account is over its 1,800-a-minute request budget (RATE_LIMITED).
errorstringoptional

A sentence for a person.

codestringoptional

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

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional

Used in