Start a session

POST/o/{org}/p/{project}/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. {project} = _ runs without a repository; a Project handle runs in that Project's repository with its connectors.

Started with an API key, the run uses Rush's models, metered on the key creator's plan, unless account_id names one of the creator's own Anthropic or OpenAI API-key accounts. A key may have max_concurrent runs in progress (default 4); one more is 429 RATE_LIMITED.

Authenticate with an org 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.

projectstringrequired

A Project's handle (name) or id, resolved inside {org} — OR the reserved sentinel _ meaning "no Project" (a direct-repo / repo-less dispatch on POST; "no Project constraint, resolve by session id alone" everywhere else). A real handle that doesn't match the session's actual Project is 404.

Request body

{project} in the path, never in the body, picks the repository. With {project} = _, agent is required.

agentstringoptional

claude, codex or opencode, optionally pinned to a CLI version: claude@2.1.291.

promptstringrequired

The task. At most 256 KiB.

at most 262144 characters
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

fast where the model row lists it in modes. OpenCode has none.

One ofstandardfast
modestringoptional
One ofheadlessinteractiveDefault "headless"
persistencestringoptional

resumable parks the sandbox with its disk and memory between turns, free while parked, for 7 idle days; ephemeral tears it down when the turn ends.

One ofresumableephemeralDefault "resumable"
account_idstringoptional

Run on one of the caller's own Anthropic or OpenAI API-key accounts instead of Rush's models.

base_branchstringoptional

Branch to start from. Not with on_pr.

on_printegeroptional

Continue on this open pull request's branch.

min 1
output_schemaobjectoptional

A JSON Schema the final answer must match; it comes back as result.structured on /result, the done event and the webhook. claude and codex only (422 FIELD_UNSUPPORTED_FOR_HARNESS otherwise). The root is type: "object"; every object lists all its properties in required (make one optional with type: [T, "null"]) and sets additionalProperties: false; $ref stays inside the document; at most 10 levels and 64 KiB. Anything else is 400 OUTPUT_SCHEMA_INVALID.

Responses

202The session, as created.

The session, as created. status is queued, allocating or running depending on admission.

execution_idstringrequired
kindstringrequired
One ofcloudlocal
org_idstring | nulloptional
Format uuid
project_idstring | nulloptional
Format uuid
agentstring | nulloptional

The harness.

statusstringrequired

paused is a resumable session parked between turns; needs_review finished without the proof it was asked for.

One ofqueuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancelledexpired
persistence_modestring | nulloptional
One ofephemeralresumablenull
machine_statestring | nulloptional

The sandbox's own lifecycle (preparing, running, pausing, paused, resuming…), separate from status.

sandbox_generationinteger | nulloptional

Increments on every resume.

promptstring | nulloptional
repo_ownerstring | nulloptional
repo_namestring | nulloptional
branchstring | nulloptional
pr_urlstring | nulloptional
summarystring | nulloptional
errorstring | nulloptional
started_byobject | nulloptional
2 fields
namestring | nulloptional
avatar_urlstring | nulloptional
input_tokensinteger | nulloptional
output_tokensinteger | nulloptional
cache_read_tokensinteger | nulloptional
cache_write_tokensinteger | nulloptional
total_tokensinteger | nulloptional

Uncached input plus cache writes plus output; null when the run reported none.

reasoning_tokensinteger | nulloptional
total_cost_usdnumber | nulloptional
modelstring | nulloptional
tool_calls_countinteger | nulloptional
tool_errors_countinteger | nulloptional
turns_countinteger | nulloptional
files_producedinteger | nulloptional
attachmentsarray of objectoptional

Files the caller attached when starting the run.

5 item fields
idstringrequired
namestringrequired
mimestringrequired
sizeintegerrequired
expired_atstring | nullrequired
Format date-time
artifactsarray of ArtifactFileoptional

The first 6 artifacts; artifact_count has the total.

3 item fields
namestringrequired
sizeintegerrequired

Bytes.

content_typestringrequired
artifact_countintegeroptional
harness_version_requestedstring | nulloptional
harness_version_resolvedstring | nulloptional
profile_idstring | nulloptional

The saved agent the run started from.

profile_revisioninteger | nulloptional
profile_digeststring | nulloptional
requested_overridesobject | nulloptional
3 fields
modelstringoptional
effortstringoptional
speedstringoptional
agent_profileobject | nulloptional
2 fields
idstringoptional
namestringoptional
effectiveobject | nulloptional

What a saved-agent run actually ran with.

6 fields
modelstring | nulloptional
effortstring | nulloptional
speedstring | nulloptional
harness_versionstring | nulloptional
catalog_revisionstring | nulloptional
image_digeststring | nulloptional
snapshotobject | nulloptional

The saved-agent configuration the run was pinned to.

effective_configobject | nulloptional

What the sandbox loaded (harness version, plugins, hooks, commands), as the runtime reported it.

session_capturestring | nulloptional
One ofcompletepartialfailednull
created_atstringrequired
Format date-time
updated_atstring | nulloptional
Format date-time
400The body is invalid: no prompt, no agent on a _ run, an unknown effort, speed or persistence, a malformed repository, or an output_schema outside the accepted subset (code OUTPUT_SCHEMA_INVALID).
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
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, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
402The plan does not cover this run: PLAN_REQUIRED (Rush's models need a paid plan), TOKEN_LIMIT_REACHED, COMPUTE_LIMIT_REACHED, WEEKLY_COMPUTE_LIMIT_REACHED, SPEND_CAP_REACHED or PAYMENT_METHOD_REQUIRED.
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
403The 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, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one that exists in an org the caller cannot see.
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
409The Project's GitHub App installation is suspended, on_pr names a pull request that is not open, or a saved agent's catalog changed since it was reviewed (CATALOG_REFRESH_REQUIRED).
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
413An attached payload is over its size limit.
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
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 (error_code MODEL_UNSUPPORTED); output_schema on opencode (FIELD_UNSUPPORTED_FOR_HARNESS); or a saved agent or sources on a key run (API_KEY_FIELD_UNSUPPORTED).
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
429The API key already has max_concurrent runs in progress (RATE_LIMITED).
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