Submit Run

POST /runs

202 for async; 200 for sync, once the run settles or the wait expires.

A replay carries Idempotent-Replay: true and the recorded body. In sync mode it still waits: the caller asked to be told how the run ended, and what was recorded is the 202 body from when the run was accepted.

Role floor

Requires member or above. The floor is a minimum, not a grant: scope filtering still applies on top of it, and a resource in another tenant answers 404 rather than 403.

Request body — RunSubmit

Field	Type		Notes
client_tools	end | suspend	optional	Default "end".
client_tool_timeout_s	integer | null	optional	min 5 max 900
agent_id	string (uuid) | null	optional	—
agent_slug	string | null	optional	max length 120
persona_id	string (uuid) | null	optional	—
revision_id	string (uuid) | null	optional	—
input	object	optional	—
session_id	string (uuid) | null	optional	—
session_key	string | null	optional	max length 255
session_title	string | null	optional	max length 300
subject	SubjectRef | null	optional	—
actor_credential	ActorCredentialSubmit | null	optional	—
response_mode	async | sync	optional	Default "async".
wait_seconds	integer | null	optional	min 1
callback_url	string | null	optional	max length 2000
lane	string | null	optional	max length 30
priority	integer	optional	Default 0. min -100 max 100
max_duration_s	integer | null	optional	min 1
idempotency_key	string | null	optional	max length 200
trace	TraceRef | null	optional	—

Responses

Status	Description	Body
202	Successful Response	RunView
422	Validation Error	HTTPValidationError

Only the success paths are declared

Any operation may also answer any status in the error catalogue, and every failure body is the platform envelope — including the 422 this document types as HTTPValidationError.

Example

The body shows the fields the schema always carries. Which combination is legal is a service rule the schema cannot express, so read the description above before copying this.

curl -X POST https://your-deployment.example.com/runs \
  -H "Authorization: Bearer $COBRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "client_tools": "end",
       "input": {},
       "response_mode": "async",
       "priority": 0
     }'

Response — RunView

Field	Type		Notes
client_tools	end | suspend	optional	Default "end".
client_tool_timeout_s	integer | null	optional	—
id	string (uuid)	required	—
status	queued | running | suspended | succeeded | failed | timed_out | cancelled	required	—
agent_id	string (uuid)	required	—
agent_revision_id	string (uuid)	required	—
persona_id	string (uuid) | null	optional	—
session_id	string (uuid) | null	required, nullable	—
parent_run_id	string (uuid) | null	required, nullable	—
root_run_id	string (uuid) | null	required, nullable	—
delegation_depth	integer	required	—
lane	string	required	—
priority	integer	required	—
trigger_kind	api | schedule | event | channel | delegation | retry | replay | maintenance | system	required	—
response_mode	async | sync | callback | ack	required	—
input	object	required	—
output	object | null	required, nullable	—
error_message	string | null	required, nullable	—
failure_class	transient | provider | tool | guardrail | budget | policy | timeout | recursion | cancelled | fatal | null	required, nullable	—
failure_detail	string | null	required, nullable	—
attempt_count	integer	required	—
max_attempts	integer	required	—
queued_at	string (date-time)	required	—
first_started_at	string (date-time) | null	required, nullable	—
completed_at	string (date-time) | null	required, nullable	—
deadline_at	string (date-time) | null	required, nullable	—
next_attempt_at	string (date-time) | null	required, nullable	—
duration_ms	integer | null	required, nullable	—
active_ms	integer	required	—
queue_ms	integer | null	required, nullable	—
phase_timings	object	required	—
usage	RunUsageView	optional	—
correlation_id	string (uuid) | null	optional	—
actor_credential_fingerprint	string | null	optional	—
actor_credential_expires_at	string (date-time) | null	optional	—
consolidation_run_id	string (uuid) | null	optional	—
persona_name	string | null	optional	—