Agent Missions REST API Reference

Package	Value
Distribution	archetype-missions

These routes are contributed only when this trusted world-library manifest is explicitly installed in the API host.

Missions

List Mission Runs

GET /v1/mission-runs

Project one bounded page of the caller's own durable runs.

Issue #809 documents no list route; the merged MCP adapter contract (#820, mission_list) requires a principal-scoped GET collection, so the page is filtered to runs the caller owns — never another principal's — and stays a pure read: no supervision resumes here.

Query parameters:

Parameter	Type	Default	Description
limit	integer	100	Bounded page size.

Response (200):

Field	Type	Required	Default	Description
runs	array[MissionRunStatusResponse]	Yes	—	Runs

Error codes: 401, 403, 422

---

Submit Mission Run

POST /v1/mission-runs

Accept one durable MissionRun under a pinned server-owned profile.

The same principal, key, and canonical digest return the original run; a changed digest under the same key returns 409. The handler dispatches the registered accept_mission_run operation and never constructs Mission ECS state, opens a runtime handle, or supervises execution.

Request body:

Field	Type	Required	Default	Description
profile_id	string	Yes	—	Profile Id
repository	string	Yes	—	Repository
branch	string	Yes	—	Branch
base_ref	string	No	"main"	Base Ref
name	string	No	"agent-mission"	Name
tasks	array[MissionRunTaskRequest]	Yes	—	Tasks

Response (202):

Field	Type	Required	Default	Description
run_id	string	Yes	—	Run Id
state	string	Yes	—	State
request_digest	string	Yes	—	Request Digest
profile	object	Yes	—	Pinned execution-profile identity recorded on the durable run.
status_url	string	Yes	—	Status Url

Error codes: 400, 401, 403, 404, 409, 422

---

Get Mission Run

GET /v1/mission-runs/{run_id}

Project one durable MissionRun the principal owns or was granted.

Path parameters:

Parameter	Type	Description
run_id	string

Response (200):

Field	Type	Required	Default	Description
run_id	string	Yes	—	Run Id
state	string	Yes	—	State
profile	object	Yes	—	Pinned execution-profile identity recorded on the durable run.
request_digest	string	Yes	—	Request Digest
world_id	string	Yes	—	World Id
mission_id	integer | null	Yes	—	Mission Id
episode_id	string	Yes	—	Episode Id
cancellation_requested	boolean	Yes	—	Cancellation Requested
cancellation_reason	string	Yes	—	Cancellation Reason
cleanup_state	string	Yes	—	Cleanup State
interrupted_reason	string	Yes	—	Interrupted Reason
accepted_at_ms	integer	Yes	—	Accepted At Ms
running_at_ms	integer | null	Yes	—	Running At Ms
terminal_at_ms	integer | null	Yes	—	Terminal At Ms
updated_at_ms	integer	Yes	—	Updated At Ms

Error codes: 401, 403, 404, 422

---

Cancel Mission Run

POST /v1/mission-runs/{run_id}/cancel

Durably record cancellation intent before reporting acceptance.

Repeated requests are idempotent; cancelling stays distinct from cancelled, and a completion race resolves to the committed execution fact through the registered cancel_mission_run operation.

Path parameters:

Parameter	Type	Description
run_id	string

Request body:

Field	Type	Required	Default	Description
reason	string	No	""	Reason

Response (202):

Field	Type	Required	Default	Description
run_id	string	Yes	—	Run Id
state	string	Yes	—	State
profile	object	Yes	—	Pinned execution-profile identity recorded on the durable run.
request_digest	string	Yes	—	Request Digest
world_id	string	Yes	—	World Id
mission_id	integer | null	Yes	—	Mission Id
episode_id	string	Yes	—	Episode Id
cancellation_requested	boolean	Yes	—	Cancellation Requested
cancellation_reason	string	Yes	—	Cancellation Reason
cleanup_state	string	Yes	—	Cleanup State
interrupted_reason	string	Yes	—	Interrupted Reason
accepted_at_ms	integer	Yes	—	Accepted At Ms
running_at_ms	integer | null	Yes	—	Running At Ms
terminal_at_ms	integer | null	Yes	—	Terminal At Ms
updated_at_ms	integer	Yes	—	Updated At Ms

Error codes: 401, 403, 404, 409, 422

---

Get Mission Run Events

GET /v1/mission-runs/{run_id}/events

Return one ordered durable event page with no gaps or duplicates.

Path parameters:

Parameter	Type	Description
run_id	string

Query parameters:

Parameter	Type	Default	Description
after	integer	0	Replay strictly after this run-local cursor.
limit	integer	100	Bounded page size.

Response (200):

Field	Type	Required	Default	Description
run_id	string	Yes	—	Run Id
after	integer	Yes	—	After
next_after	integer	Yes	—	Next After
events	array[MissionRunEventResponse]	Yes	—	Events

Error codes: 401, 403, 404, 422

---

Get Mission Run Result

GET /v1/mission-runs/{run_id}/result

Return the one immutable bounded terminal result, or 425 while open.

Path parameters:

Parameter	Type	Description
run_id	string

Response (200):

Field	Type	Required	Default	Description
run_id	string	Yes	—	Run Id
state	string	Yes	—	State
result	MissionRunResultDetailResponse | null	Yes	—
interrupted_reason	string	Yes	—	Interrupted Reason

Error codes: 401, 403, 404, 422, 425

---

List Missions

GET /worlds/{world_id}/missions

List mission entities with their current rollup state.

Path parameters:

Parameter	Type	Description
world_id	string

Error codes: 422

---

Get Mission Tasks

GET /worlds/{world_id}/missions/{mission_id}/tasks

Project one mission's task DAG and dependency edges.

Path parameters:

Parameter	Type	Description
world_id	string
mission_id	integer

Error codes: 422

---

Get Task Card

GET /worlds/{world_id}/tasks/{task_id}

Project one task's state, validators, executions, and results.

Path parameters:

Parameter	Type	Description
world_id	string
task_id	integer

Error codes: 422

---