BidAuthorBidAuthor
Get Started
API reference

Runs

10 endpoints under /v1/runs.

List Runs

get/v1/runs

Query parameters

  • ownerenumoptional
    meorg
  • statusstringoptional

    'open', 'terminal', or one run status.

  • kindenumoptional
    arthurtask_workoutlineplacesubmissioncompose
  • root_run_idstring (uuid)optional

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Get Run

get/v1/runs/{run_id}

Path parameters

  • run_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Cancel Run

post/v1/runs/{run_id}/cancel

Stop the run and every open run under it. Race-guarded: a run that finished before the write stays finished.

Path parameters

  • run_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Get Run Context

get/v1/runs/{run_id}/context

List every model call the run made, in order, with the newest window block by block. Follow GET /runs/{run_id}/stream from here: each new call arrives as a stage="context" frame.

Path parameters

  • run_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Get Run Context Step

get/v1/runs/{run_id}/context/{manifest_id}

Return one model call's window, with its blocks' text when kept.

Path parameters

  • run_idstring (uuid)required
  • manifest_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Get Run Live Bodies

get/v1/runs/{run_id}/live-bodies

Return what an open run has written so far, per subject. Follow the run's stream from each body's cursor (attach contract in :mod:domains.runs.live_body). A closed run has none: its subjects' own records hold the result.

Path parameters

  • run_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Resume Run

post/v1/runs/{run_id}/resume

Answer the approval a run paused on (needs_input). approve starts the work it holds; decline cancels it as declined. The owner answers, or an org admin for someone else's run. A run not awaiting approval answers 409 run_not_awaiting_approval.

Path parameters

  • run_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Request body

  • decisionenumrequired

    Owner's answer to a run paused on approval (POST /runs/{id}/resume).

    approvedecline

Failures return the error envelope; branch on error_code.

Request
Response

Stream Run

get/v1/runs/{run_id}/stream

Stream the run's own detail (an Arthur turn's content parts and tool steps). The first frame is connected with the run's current card, so a late client can draw it before any detail arrives. A finished run gets that frame plus the replay requested, then the stream closes.

Path parameters

  • run_idstring (uuid)required

Query parameters

  • sincestringoptional

    Resume cursor: the last event id seen. '0-0' replays the retained history; '$' (default) is new frames only.

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Get Run Tree

get/v1/runs/{run_id}/tree

Path parameters

  • run_idstring (uuid)required

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response

Stream My Runs

get/v1/runs/live

Stream a stage="run" frame for every lifecycle change of the caller's runs. Covers every run the caller owns, whatever started it (a view, Arthur, an API key, a schedule).

Query parameters

  • sincestringoptional

    Resume cursor: the last event id seen. '0-0' replays the retained history; '$' (default) is new frames only.

Headers

  • X-Organization-IDstringoptional
  • X-Workspace-IDstringoptional

Failures return the error envelope; branch on error_code.

Request
Response