---
title: "Create a mission: mints the tracker issue and starts the run in one call"
method: POST
path: "/missions"
tags: ["missions"]
---

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

`POST /missions`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/missions`
- Auth: none declared

For a caller delegating work that has no tracker issue yet (typically a locally-authored spec handed over from a terminal). Creates a real issue in the project's tracker under your own connector (a Linear issue, or a GitHub issue on the project's repository for a GitHub-Issues project; a project with no tracker gets a platform-minted id), writes the hand-off against it, and starts the run last: by then the hand-off is already stored, so a mission never starts against a half-written entry. Use POST /missions/{issueId}/start instead when the issue already exists.

## Headers

- `idempotency-key` string: Retrying a request with the same key charges it once and starts (or delivers) it once. Use a new key for new work.

## Request body

- CreateMissionRequest
  - `projectId` string, required
  - `title` string: Omit only when `entry.prNumber` is set — the pull request's own title is then used.
  - `description` string: Issue body. Acceptance criteria written here are parsed by the planner as it would for any issue.
  - `labels` string[]
  - `entry` object
    - `startAt` 'builder' | 'reviewer' | 'qa', nullable, required
    - `plan` string
    - `prNumber` integer
    - `filePlan` MissionEntryFilePlanEntry[]
      - `path` string, required
      - `action` 'create' | 'modify' | 'delete', required
      - `description` string
    - `acceptanceCriteria` string[]
  - `agents` object: 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.
    - `planner` AgentsOverrideRoleEntry
      - `harness` 'claude-code' | 'codex' | 'pi' | 'kilo-code' | 'open-code'
      - `model` string
      - `provider` string
      - `effort` string
      - `providerRouting` object
        - `order` string[]
        - `only` string[]
        - `ignore` string[]
        - `allowFallbacks` boolean
        - `requireParameters` boolean
        - `quantizations` string[]
        - `sort` string
        - `dataCollection` 'allow' | 'deny'
      - `checkpoint` boolean
      - `rejectOn` 'critical' | 'suggestion' | 'trivial'
      - `prompt` union
        - string
        - AgentsOverrideInlinePrompt
          - `content` string, required
          - `mode` 'replace' | 'extend'
        - AgentsOverridePathPrompt
          - `path` string, required
          - `ref` string
          - `mode` 'replace' | 'extend'
      - `sandbox` string
      - `size` union
        - 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4'
        - object
          - `vcpu` integer, required
          - `memoryMib` integer, required
          - `diskMb` integer, required
      - `mcp` union[]: Optional narrowing of the role's MCP servers/tools for this mission; can only remove access.
        - union
          - string
          - object
            - `server` string, required
            - `tools` string[]
    - `builder` AgentsOverrideRoleEntry
      - `harness` 'claude-code' | 'codex' | 'pi' | 'kilo-code' | 'open-code'
      - `model` string
      - `provider` string
      - `effort` string
      - `providerRouting` object
        - `order` string[]
        - `only` string[]
        - `ignore` string[]
        - `allowFallbacks` boolean
        - `requireParameters` boolean
        - `quantizations` string[]
        - `sort` string
        - `dataCollection` 'allow' | 'deny'
      - `checkpoint` boolean
      - `rejectOn` 'critical' | 'suggestion' | 'trivial'
      - `prompt` union
        - string
        - AgentsOverrideInlinePrompt
          - `content` string, required
          - `mode` 'replace' | 'extend'
        - AgentsOverridePathPrompt
          - `path` string, required
          - `ref` string
          - `mode` 'replace' | 'extend'
      - `sandbox` string
      - `size` union
        - 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4'
        - object
          - `vcpu` integer, required
          - `memoryMib` integer, required
          - `diskMb` integer, required
      - `mcp` union[]: Optional narrowing of the role's MCP servers/tools for this mission; can only remove access.
        - union
          - string
          - object
            - `server` string, required
            - `tools` string[]
    - `reviewer` AgentsOverrideRoleEntry
      - `harness` 'claude-code' | 'codex' | 'pi' | 'kilo-code' | 'open-code'
      - `model` string
      - `provider` string
      - `effort` string
      - `providerRouting` object
        - `order` string[]
        - `only` string[]
        - `ignore` string[]
        - `allowFallbacks` boolean
        - `requireParameters` boolean
        - `quantizations` string[]
        - `sort` string
        - `dataCollection` 'allow' | 'deny'
      - `checkpoint` boolean
      - `rejectOn` 'critical' | 'suggestion' | 'trivial'
      - `prompt` union
        - string
        - AgentsOverrideInlinePrompt
          - `content` string, required
          - `mode` 'replace' | 'extend'
        - AgentsOverridePathPrompt
          - `path` string, required
          - `ref` string
          - `mode` 'replace' | 'extend'
      - `sandbox` string
      - `size` union
        - 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4'
        - object
          - `vcpu` integer, required
          - `memoryMib` integer, required
          - `diskMb` integer, required
      - `mcp` union[]: Optional narrowing of the role's MCP servers/tools for this mission; can only remove access.
        - union
          - string
          - object
            - `server` string, required
            - `tools` string[]
    - `qa` AgentsOverrideRoleEntry
      - `harness` 'claude-code' | 'codex' | 'pi' | 'kilo-code' | 'open-code'
      - `model` string
      - `provider` string
      - `effort` string
      - `providerRouting` object
        - `order` string[]
        - `only` string[]
        - `ignore` string[]
        - `allowFallbacks` boolean
        - `requireParameters` boolean
        - `quantizations` string[]
        - `sort` string
        - `dataCollection` 'allow' | 'deny'
      - `checkpoint` boolean
      - `rejectOn` 'critical' | 'suggestion' | 'trivial'
      - `prompt` union
        - string
        - AgentsOverrideInlinePrompt
          - `content` string, required
          - `mode` 'replace' | 'extend'
        - AgentsOverridePathPrompt
          - `path` string, required
          - `ref` string
          - `mode` 'replace' | 'extend'
      - `sandbox` string
      - `size` union
        - 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4'
        - object
          - `vcpu` integer, required
          - `memoryMib` integer, required
          - `diskMb` integer, required
      - `mcp` union[]: Optional narrowing of the role's MCP servers/tools for this mission; can only remove access.
        - union
          - string
          - object
            - `server` string, required
            - `tools` string[]

## Response `201`

Created

- CreateMissionResponse
  - `issueId` string, required
  - `identifier` string, required
  - `url` string, required

## Other responses

- `400`: A GitHub-Issues project has no issue code to mint the mission's id with
- `402`: The org has no credits for this (code credits_exhausted)
- `403`: Forbidden
- `404`: Project not accessible
- `422`: entry.startAt=reviewer|qa requires entry.prNumber
- `429`: The org reached its daily mission limit (code daily_limit_reached)
- `502`: The tracker call (Linear or GitHub) failed (code tracker_unavailable, retryable), or the issue was created but not assigned to the agent (code tracker_assign_failed, names the issue)
- `503`: Project has no tracker team — finish onboarding; or Linear no longer accepts the project's authorization, or GitHub refused the App installation's token (code tracker_reconnect_required)

---

[API](https://skmtc.dev/letsship/apis/ship-api.md) · [All operations](https://skmtc.dev/letsship/apis/ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsship/apis/ship-api/revisions/e6eac1bcadd4?raw)