Missions ~ SHIP

Start missions, read their state, steer them, and override how their agents run.

List ticket+PR sessions for the caller's accessible projects

Query Parameters

projectId?string

search?string

status?string

Value in

"pending"
"supervisor"
"planning"
"coding"
"ci"
"review"
"deploying"
"qa"
"done"
"declined"
"needs_attention"

activity?string

Value in

"queued"
"planning"
"building"
"fixing_ci"
"addressing_review"
"addressing_qa"
"ci_running"
"ci_failed"
"reviewing"
"changes_requested"
"deploying"
"testing"
"qa_failed"
"ready_to_merge"
"auto_merging"
"needs_attention"
"merged"
"auto_merged"
"declined"
"paused"
"stopped"

pipelineProgress?string

Value in

"no_pr"
"ci_failed"
"review_changes_requested"
"qa_failed"
"awaiting_review"
"awaiting_deploy"
"awaiting_qa"
"running"
"awaiting_ci"
"ready_for_human"
"merged"
"declined"
"failed"

checkState?string

Value in

"passed"
"failed"
"pending"
"none"

reviewState?string

Value in

"approved"
"changes_requested"
"pending"
"none"

awaitingAcceptance?boolean|null

excludeClosed?boolean|null

archived?boolean|null

disposition?string

Value in

"product"
"probe"
"superseded"
"takeover"

excludeProbes?boolean|null

limit?integer

Range1 <= value <= 100

Default25

offset?|

Range0 <= value

Default0

`application/json`

curl -X GET "https://example.com/missions"

{  "data": [    {      "issueId": "string",      "projectId": "string",      "orgSlug": "string",      "linearTitle": "string",      "linearUrl": "string",      "prNumber": 0,      "prUrl": "string",      "ciUrl": "string",      "repo": "string",      "baseBranch": "string",      "headBranch": "string",      "checkState": "passed",      "reviewState": "approved",      "testState": "passed",      "diffAdded": 0,      "diffRemoved": 0,      "pipelineProgress": "no_pr",      "activity": "queued",      "statusLabel": "string",      "currentStage": "pending",      "cycleTimeMs": 0,      "cycleTimeRunning": true,      "paused": true,      "pauseSource": "string",      "stopped": true,      "stopping": true,      "terminal": true,      "prActionPending": "merge",      "mergeConflict": true,      "autoMerge": true,      "archived": true,      "entryStage": "builder",      "totalCostUsd": 0,      "updatedAt": 0,      "laneEnteredAt": 0,      "platformVersion": "string",      "environment": "string",      "straddled": true,      "disposition": "product",      "supersededBy": "string",      "dispositionSignal": "string"    }  ],  "total": 0,  "nextCursor": "string"}

Create a mission: mints the tracker issue and starts the run in one call

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

projectId*string

Length1 <= length

title?string

Omit only when entry.prNumber is set — the pull request's own title is then used.

Length1 <= length <= 200

description?string

Issue body. Acceptance criteria written here are parsed by the planner as it would for any issue.

Lengthlength <= 10000

labels?array<string>

Itemsitems <= 10

entry?

agents?

Per-role harness/model override for THIS mission, identical in shape and precedence to PUT /missions/{issueId}/agents-override. Carried here because a created mission has no id until this call returns — setting it afterwards races the first dispatch.

Response Body

`application/json`

curl -X POST "https://example.com/missions" \  -H "Content-Type: application/json" \  -d '{    "projectId": "string"  }'

{  "issueId": "string",  "identifier": "string",  "url": "string"}

Session detail: summary + role-based runs + stage swimlane

Path Parameters

issueId*string

Length1 <= length

Query Parameters

orgSlug?string

projectId?string

Response Body

`application/json`

curl -X GET "https://example.com/missions/string"

{  "summary": {    "issueId": "string",    "projectId": "string",    "orgSlug": "string",    "linearTitle": "string",    "linearUrl": "string",    "prNumber": 0,    "prUrl": "string",    "ciUrl": "string",    "repo": "string",    "baseBranch": "string",    "headBranch": "string",    "checkState": "passed",    "reviewState": "approved",    "testState": "passed",    "diffAdded": 0,    "diffRemoved": 0,    "pipelineProgress": "no_pr",    "activity": "queued",    "statusLabel": "string",    "currentStage": "pending",    "cycleTimeMs": 0,    "cycleTimeRunning": true,    "paused": true,    "pauseSource": "string",    "stopped": true,    "stopping": true,    "terminal": true,    "prActionPending": "merge",    "mergeConflict": true,    "autoMerge": true,    "archived": true,    "entryStage": "builder",    "totalCostUsd": 0,    "updatedAt": 0,    "laneEnteredAt": 0,    "platformVersion": "string",    "environment": "string",    "straddled": true,    "disposition": "product",    "supersededBy": "string",    "dispositionSignal": "string"  },  "runs": [    {      "sandboxId": "string",      "role": "string",      "label": "string",      "status": "running",      "harness": "string",      "model": "string",      "provider": "string",      "servedProvider": "string",      "effort": "string",      "outcome": "string",      "createdAt": 0,      "destroyedAt": 0,      "latestSessionId": "string",      "tokenUsage": {        "totalCostUsd": 0,        "inputTokens": 0,        "outputTokens": 0      },      "isCurrent": true,      "result": {        "scope": "run",        "plan": {          "markdown": "string",          "acceptanceCriteria": [            "string"          ],          "filePlan": [            {              "path": "string",              "action": "create",              "description": "string"            }          ]        },        "build": {          "prNumber": 0,          "prUrl": "string",          "headSha": "string",          "commitUrl": "string",          "diffAdded": 0,          "diffRemoved": 0,          "changedFiles": 0,          "files": [            {              "path": "string",              "additions": 0,              "deletions": 0,              "status": "string"            }          ]        },        "review": {          "approved": true,          "comments": [            {              "file": "string",              "line": 0,              "severity": "critical",              "comment": "string"            }          ]        },        "qa": {          "overall": "pass",          "criteria": [            {              "name": "string",              "pass": true,              "evidence": "string"            }          ],          "proofSkipped": true        },        "failure": "string"      },      "platformVersion": "string"    }  ],  "stages": [    {      "stage": "pending",      "state": "done",      "role": "string",      "sandboxId": "string"    }  ],  "events": [    {      "ts": 0,      "kind": "planner_done",      "label": "string",      "detail": "string",      "sandboxId": "string"    }  ],  "stats": {    "cycleTimeMs": 0,    "leadTimeMs": 0,    "leadTimeRunning": true,    "totalCostUsd": 0,    "totalInputTokens": 0,    "totalOutputTokens": 0,    "agentAttempts": 0,    "stages": [      {        "stage": "pending",        "label": "string",        "attempts": 0,        "durationMs": 0,        "percentOfCycle": 0,        "costUsd": 0,        "inputTokens": 0,        "outputTokens": 0,        "model": "string",        "promptVersion": "string"      }    ]  },  "stageOutcomes": {    "plan": {      "markdown": "string",      "acceptanceCriteria": [        "string"      ],      "filePlan": [        {          "path": "string",          "action": "create",          "description": "string"        }      ]    },    "build": {      "prNumber": 0,      "prUrl": "string",      "headSha": "string",      "commitUrl": "string",      "diffAdded": 0,      "diffRemoved": 0,      "changedFiles": 0,      "files": [        {          "path": "string",          "additions": 0,          "deletions": 0,          "status": "string"        }      ]    },    "review": {      "approved": true,      "comments": [        {          "file": "string",          "line": 0,          "severity": "critical",          "comment": "string"        }      ]    },    "qa": {      "overall": "pass",      "criteria": [        {          "name": "string",          "pass": true,          "evidence": "string"        }      ],      "proofSkipped": true    }  },  "proofRunSandboxId": "string"}

Set (or clear) the human-asserted mission disposition (admin+): why the mission ended

Path Parameters

issueId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

disposition*|

Value in

"product"
"probe"
"superseded"
"takeover"

supersededBy?|

Length1 <= length

Response Body

`application/json`

curl -X PATCH "https://example.com/missions/string" \  -H "Content-Type: application/json" \  -d '{    "disposition": "product"  }'

{  "ok": true,  "issueId": "string",  "disposition": "product",  "supersededBy": "string"}

Raw per-attempt provenance records (harness/model/provider, token tiers, cost, duration)

Path Parameters

issueId*string

Length1 <= length

Query Parameters

orgSlug?string

projectId?string

Response Body

`application/json`

curl -X GET "https://example.com/missions/string/provenance"

{  "data": [    {      "stage": "string",      "attempt": 0,      "harness": "string",      "model": "string",      "provider": "string",      "effort": "string",      "baseSha": "string",      "durationSeconds": 0,      "inferenceCostUsd": 0,      "inputTokens": 0,      "outputTokens": 0,      "cacheReadTokens": 0,      "cacheCreationTokens": 0,      "selfReportedCostUsd": 0,      "priceVersion": "string",      "startedAt": "string",      "completedAt": "string",      "sessionId": "string"    }  ]}

Typed mission-inspection report: everything recorded about one mission, as one contract

Path Parameters

issueId*string

Length1 <= length

Query Parameters

orgSlug?string

projectId?string

sections?string

Comma-separated section filter; default all.

Response Body

`application/json`

curl -X GET "https://example.com/missions/string/inspect"

{  "issueId": "string",  "projectId": "string",  "taskId": "string",  "generatedAt": "string",  "sections": {    "taskState": {      "ok": true,      "data": null,      "error": "string"    },    "retryReason": {      "ok": true,      "data": null,      "error": "string"    },    "ciSummary": {      "ok": true,      "data": null,      "error": "string"    },    "builderRetryBrief": {      "ok": true,      "data": null,      "error": "string"    },    "dispatchError": {      "ok": true,      "data": null,      "error": "string"    },    "latestReview": {      "ok": true,      "data": null,      "error": "string"    },    "latestQa": {      "ok": true,      "data": null,      "error": "string"    },    "runIndex": {      "ok": true,      "data": null,      "error": "string"    },    "provenance": {      "ok": true,      "data": null,      "error": "string"    },    "sessionSummaries": {      "ok": true,      "data": null,      "error": "string"    },    "sandboxes": {      "ok": true,      "data": null,      "error": "string"    },    "streamHeads": {      "ok": true,      "data": null,      "error": "string"    }  }}

Pause (soft-hold) the development pipeline - enqueues to the orchestrator

Path Parameters

issueId*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/missions/string/pause"

{  "ok": true,  "issueId": "string"}

Resume a paused development pipeline - enqueues to the orchestrator

Path Parameters

issueId*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/missions/string/resume"

{  "ok": true,  "issueId": "string"}

Send a follow-up instruction to a mission

Path Parameters

issueId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

body*string

What the agents should do. Travels verbatim into the builder's prompt.

Length1 <= length <= 10000

kind?MissionInstructionKind

follow_up asks for a change and dispatches the builder against the mission's open PR, overriding cached review/QA verdicts. note records context for whatever runs next and dispatches nothing. Stated explicitly rather than inferred, so the outcome never depends on how the platform reads intent.

Default"follow_up"

Value in

"follow_up"
"note"

Response Body

`application/json`

curl -X POST "https://example.com/missions/string/instructions" \  -H "Content-Type: application/json" \  -d '{    "body": "string"  }'

{  "instructionId": "string",  "issueId": "string",  "recorded": true,  "missionActivity": "string",  "dispatch": {    "willDispatch": true,    "role": "string",    "reason": "follow_up_forced",    "remedy": "string"  }}

Start a mission: the entry point for handing an existing plan or build off to the fleet

Path Parameters

issueId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

projectId*string

Length1 <= length

startAt?string

Value in

"builder"
"reviewer"
"qa"

plan?string

Length1 <= length

prNumber?integer

Range0 < value

filePlan?array<>

Builder entry only. Files the supplied plan expects to touch.

Itemsitems <= 200

acceptanceCriteria?array<>

Builder entry only. Criteria supplied with the plan; they win over the ones scraped from the issue body.

Itemsitems <= 50

agents?

Per-role harness/model override for THIS mission, identical in shape and precedence to PUT /missions/{issueId}/agents-override. Written before the run is triggered, so it is in place when the first stage dispatches.

Response Body

`application/json`

curl -X POST "https://example.com/missions/string/start" \  -H "Content-Type: application/json" \  -d '{    "projectId": "string"  }'

{  "ok": true,  "issueId": "string"}

`application/json`

curl -X POST "https://example.com/missions/string/stop"

{  "ok": true,  "issueId": "string"}

`application/json`

curl -X POST "https://example.com/missions/string/archive"

{  "ok": true,  "issueId": "string"}

`application/json`

curl -X POST "https://example.com/missions/string/unarchive"

{  "ok": true,  "issueId": "string"}

`application/json`

curl -X POST "https://example.com/missions/string/merge"

{  "ok": true,  "issueId": "string"}

`application/json`

curl -X POST "https://example.com/missions/string/decline"

{  "ok": true,  "issueId": "string"}

Use the request body type in TypeScript.

enabled*boolean

Response Body

`application/json`

curl -X POST "https://example.com/missions/string/auto-merge" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'

{  "ok": true,  "issueId": "string",  "autoMerge": true}

`application/json`

curl -X GET "https://example.com/missions/string/agents-override?projectId=string"

{  "issueId": "string",  "override": {    "agents": {      "planner": {        "harness": "claude-code",        "model": "string",        "provider": "string",        "effort": "string",        "providerRouting": {          "order": [            "string"          ],          "only": [            "string"          ],          "ignore": [            "string"          ],          "allowFallbacks": true,          "requireParameters": true,          "quantizations": [            "string"          ],          "sort": "string",          "dataCollection": "allow"        },        "checkpoint": true,        "rejectOn": "critical",        "prompt": "string"      },      "builder": {        "harness": "claude-code",        "model": "string",        "provider": "string",        "effort": "string",        "providerRouting": {          "order": [            "string"          ],          "only": [            "string"          ],          "ignore": [            "string"          ],          "allowFallbacks": true,          "requireParameters": true,          "quantizations": [            "string"          ],          "sort": "string",          "dataCollection": "allow"        },        "checkpoint": true,        "rejectOn": "critical",        "prompt": "string"      },      "reviewer": {        "harness": "claude-code",        "model": "string",        "provider": "string",        "effort": "string",        "providerRouting": {          "order": [            "string"          ],          "only": [            "string"          ],          "ignore": [            "string"          ],          "allowFallbacks": true,          "requireParameters": true,          "quantizations": [            "string"          ],          "sort": "string",          "dataCollection": "allow"        },        "checkpoint": true,        "rejectOn": "critical",        "prompt": "string"      },      "qa": {        "harness": "claude-code",        "model": "string",        "provider": "string",        "effort": "string",        "providerRouting": {          "order": [            "string"          ],          "only": [            "string"          ],          "ignore": [            "string"          ],          "allowFallbacks": true,          "requireParameters": true,          "quantizations": [            "string"          ],          "sort": "string",          "dataCollection": "allow"        },        "checkpoint": true,        "rejectOn": "critical",        "prompt": "string"      }    },    "baseBranch": "string"  }}

`application/json`

curl -X DELETE "https://example.com/missions/string/agents-override?projectId=string"

{  "ok": true,  "issueId": "string"}

Set a per-issue agents/baseBranch override — merged per-role, per-field onto the repo's ship.yml at resolution time (override field, then ship.yml field, then platform defaults); a role or field the override omits resolves from ship.yml

Path Parameters

issueId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

projectId*string

Length1 <= length

agents?

baseBranch?string

Length1 <= length

Response Body

`application/json`

curl -X PUT "https://example.com/missions/string/agents-override" \  -H "Content-Type: application/json" \  -d '{    "projectId": "string"  }'

{  "ok": true,  "issueId": "string"}

Missions

200application/json

401application/json

201application/json

403application/json

404application/json

422application/json

503application/json

200application/json

404application/json

200application/json

403application/json

404application/json

422application/json

200application/json

404application/json

200application/json

400application/json

404application/json

200application/json

404application/json

200application/json

404application/json

200application/json

403application/json

404application/json

200application/json

403application/json

404application/json

422application/json

200application/json

404application/json

200application/json

403application/json

404application/json

200application/json

403application/json

404application/json

200application/json

404application/json

409application/json

502application/json

200application/json

404application/json

502application/json

200application/json

404application/json

200application/json

404application/json

200application/json

403application/json

404application/json

200application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`