Skip to content
nikcli
Docs
Documentation

Missions

Mission definitions, their feature list, and the execution lifecycle — start, pause, cancel — along with recent executions.

Playground

Send these requests to your own running server. Values stay in this browser.

Not connected
How this works

Start a server with nikcli serve --hostname 127.0.0.1 --port 4096. Requests go straight from this page to that address — the browser allows it because loopback counts as a secure origin, and the server allows it because nikcli-ai.dev is in its CORS allowlist.

To try things without touching your real sessions or config, start the server with NIKCLI_TEST_HOME pointed at a throwaway directory — see the guided tour.

Operations

13 endpoints, generated from the server's own OpenAPI document. Every path also accepts the directory and workspace query parameters that select which instance handles the request.

get /mission mission.list
put /mission mission.upsert
get /mission/templates mission.templates
post /mission/generate mission.generate
get /mission/execs/recent mission.recentExecs
get /mission/{id} mission.get
post /mission/{id} mission.update
delete /mission/{id} mission.delete
post /mission/{id}/start mission.start
post /mission/{id}/pause mission.pause
post /mission/{id}/cancel mission.cancel
post /mission/{id}/feature/{featureID} mission.feature.mutate
get /mission/{id}/execs mission.execs
get /mission # mission.list
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 MissionListOutput application/json 
{
  missions: MissionDefinition[]
  runtimes: MissionRuntime[]
}
Example response captured 
{
  "missions": [],
  "runtimes": []
}
SDK example
mission.list
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.list({
  ...
})
Try it
put /mission # mission.upsert
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  name: string
  brief: string
  milestones: ({
    id: string
    name: string
    features: ({
      id: string
      name: string
      objective: string
      agent: string
      model?: string | null
      tokenBudget?: 
        | 
        | number
        | "Infinity" | "-Infinity" | "NaN"
        | null
      dependsOn?: string[] | null
      status?: 
        | 
        | "pending"
        | "running"
        | "done"
        | "blocked"
        | "skipped"
        | "error"
        | null
      error?: string | null
    })[]
    validation?: 
      | "scrutiny" | "user-test" | "none"
      | null
    status?: 
      | 
      | "pending"
      | "running"
      | "validating"
      | "done"
      | "blocked"
      | null
  })[]
  models?: 
    | {
    worker?: string | null
    validation?: string | null
    orchestrator?: string | null
  }
    | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  sandbox?: boolean | null
  worktree?: 
    | {
    name: string
    branch?: string | null
    directory: string
  }
    | null
}
Responses
200 MissionDefinition application/json 
{
  id: string
  name: string
  brief: string
  milestones: MissionMilestone[]
  models: MissionModels
  timeoutMs?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  sandbox?: boolean
  worktree?: MissionWorktree
  status: 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
400 MissionValidationError application/json 
{
  name: "ValidationError"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "name": "",
  "brief": "",
  "milestones": [
    {
      "id": "",
      "name": "",
      "features": [],
      "validation": "scrutiny",
      "status": "pending"
    }
  ],
  "models": {
    "worker": "",
    "validation": "",
    "orchestrator": ""
  },
  "timeoutMs": 0,
  "sandbox": false,
  "worktree": {
    "name": "",
    "branch": "",
    "directory": ""
  },
  "status": "planning",
  "createdAt": 0
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.upsert
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.upsert({
  ...
})
Try it
get /mission/templates # mission.templates
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Responses
200 MissionTemplatesOutput application/json 
{
  templates: MissionTemplate[]
}
Example response from schema 
{
  "templates": [
    {
      "id": "",
      "title": "",
      "description": "",
      "brief": ""
    }
  ]
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.templates
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.templates({
  ...
})
Try it
post /mission/generate # mission.generate
Parameters
Name In Type Required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  description: string
  model?: string
  agent?: string
  sessionID?: string
}
Responses
200 MissionDefinition application/json 
{
  id: string
  name: string
  brief: string
  milestones: MissionMilestone[]
  models: MissionModels
  timeoutMs?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  sandbox?: boolean
  worktree?: MissionWorktree
  status: 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
400 MissionValidationError application/json 
{
  name: "ValidationError"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "name": "",
  "brief": "",
  "milestones": [
    {
      "id": "",
      "name": "",
      "features": [],
      "validation": "scrutiny",
      "status": "pending"
    }
  ],
  "models": {
    "worker": "",
    "validation": "",
    "orchestrator": ""
  },
  "timeoutMs": 0,
  "sandbox": false,
  "worktree": {
    "name": "",
    "branch": "",
    "directory": ""
  },
  "status": "planning",
  "createdAt": 0
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.generate
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.generate({
  ...
})
Try it
get /mission/execs/recent # mission.recentExecs
Parameters
Name In Type Required
limit query string optional
directory query string optional
workspace query string optional
Responses
200 MissionExecsOutput application/json 
{
  execs: MissionExec[]
}
Example response from schema 
{
  "execs": [
    {
      "id": "",
      "missionID": "",
      "kind": "feature",
      "targetID": "",
      "targetName": "",
      "startedAt": 0,
      "endedAt": 0,
      "status": "running",
      "heartbeatAt": 0,
      "sessionID": "",
      "error": "",
      "ok": false
    }
  ]
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.recentExecs
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.recentExecs({
  ...
})
Try it
get /mission/{id} # mission.get
Parameters
Name In Type Required
id path string required
directory query string optional
workspace query string optional
Responses
200 MissionGetOutput application/json 
{
  mission: MissionDefinition
  runtime: MissionRuntime
}
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "mission": {
    "id": "",
    "name": "",
    "brief": "",
    "milestones": [
      {
        "id": null,
        "name": null,
        "features": null,
        "validation": null,
        "status": null
      }
    ],
    "models": {
      "worker": "",
      "validation": "",
      "orchestrator": ""
    },
    "timeoutMs": 0,
    "sandbox": false,
    "worktree": {
      "name": "",
      "branch": "",
      "directory": ""
    },
    "status": "planning",
    "createdAt": 0
  },
  "runtime": {
    "missionID": "",
    "status": "idle",
    "sessionID": "",
    "currentMilestoneID": "",
    "currentFeatureID": "",
    "doneFeatures": 0,
    "totalFeatures": 0,
    "lastError": "",
    "lastRunAt": 0
  }
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.get
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.get({
  ...
})
Try it
post /mission/{id} # mission.update
Parameters
Name In Type Required
id path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  name: string
  brief: string
  milestones: ({
    id: string
    name: string
    features: ({
      id: string
      name: string
      objective: string
      agent: string
      model?: string | null
      tokenBudget?: 
        | 
        | number
        | "Infinity" | "-Infinity" | "NaN"
        | null
      dependsOn?: string[] | null
      status?: 
        | 
        | "pending"
        | "running"
        | "done"
        | "blocked"
        | "skipped"
        | "error"
        | null
      error?: string | null
    })[]
    validation?: 
      | "scrutiny" | "user-test" | "none"
      | null
    status?: 
      | 
      | "pending"
      | "running"
      | "validating"
      | "done"
      | "blocked"
      | null
  })[]
  models?: 
    | {
    worker?: string | null
    validation?: string | null
    orchestrator?: string | null
  }
    | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  sandbox?: boolean | null
  worktree?: 
    | {
    name: string
    branch?: string | null
    directory: string
  }
    | null
  status?: 
    | 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
    | null
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
Responses
200 MissionDefinition application/json 
{
  id: string
  name: string
  brief: string
  milestones: MissionMilestone[]
  models: MissionModels
  timeoutMs?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  sandbox?: boolean
  worktree?: MissionWorktree
  status: 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
400 MissionValidationError application/json 
{
  name: "ValidationError"
  data: { [key: string]: unknown }
}
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "name": "",
  "brief": "",
  "milestones": [
    {
      "id": "",
      "name": "",
      "features": [],
      "validation": "scrutiny",
      "status": "pending"
    }
  ],
  "models": {
    "worker": "",
    "validation": "",
    "orchestrator": ""
  },
  "timeoutMs": 0,
  "sandbox": false,
  "worktree": {
    "name": "",
    "branch": "",
    "directory": ""
  },
  "status": "planning",
  "createdAt": 0
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.update
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.update({
  ...
})
Try it
delete /mission/{id} # mission.delete
Parameters
Name In Type Required
id path string required
directory query string optional
workspace query string optional
Responses
200 MissionBooleanResult application/json 
boolean
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.delete
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.delete({
  ...
})
Try it

This changes or removes server state, against whatever base URL is set above.

post /mission/{id}/start # mission.start
Parameters
Name In Type Required
id path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  sessionID?: string | null
}
Responses
200 MissionBooleanResult application/json 
boolean
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.start
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.start({
  ...
})
Try it
post /mission/{id}/pause # mission.pause
Parameters
Name In Type Required
id path string required
directory query string optional
workspace query string optional
Responses
200 MissionBooleanResult application/json 
boolean
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.pause
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.pause({
  ...
})
Try it
post /mission/{id}/cancel # mission.cancel
Parameters
Name In Type Required
id path string required
directory query string optional
workspace query string optional
Responses
200 MissionBooleanResult application/json 
boolean
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
false

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.cancel
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.cancel({
  ...
})
Try it
post /mission/{id}/feature/{featureID} # mission.feature.mutate
Parameters
Name In Type Required
id path string required
featureID path string required
directory query string optional
workspace query string optional
Request body · required · application/json 
{
  status?: 
    | 
    | "pending"
    | "running"
    | "done"
    | "blocked"
    | "skipped"
    | "error"
    | null
  error?: string | null
  appendDependsOn?: string[] | null
}
Responses
200 MissionDefinition application/json 
{
  id: string
  name: string
  brief: string
  milestones: MissionMilestone[]
  models: MissionModels
  timeoutMs?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  sandbox?: boolean
  worktree?: MissionWorktree
  status: 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
400 MissionValidationError application/json 
{
  name: "ValidationError"
  data: { [key: string]: unknown }
}
404 MissionNotFound application/json 
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
Example response from schema 
{
  "id": "",
  "name": "",
  "brief": "",
  "milestones": [
    {
      "id": "",
      "name": "",
      "features": [],
      "validation": "scrutiny",
      "status": "pending"
    }
  ],
  "models": {
    "worker": "",
    "validation": "",
    "orchestrator": ""
  },
  "timeoutMs": 0,
  "sandbox": false,
  "worktree": {
    "name": "",
    "branch": "",
    "directory": ""
  },
  "status": "planning",
  "createdAt": 0
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.feature.mutate
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.feature.mutate({
  ...
})
Try it
get /mission/{id}/execs # mission.execs
Parameters
Name In Type Required
id path string required
limit query string optional
directory query string optional
workspace query string optional
Responses
200 MissionExecsOutput application/json 
{
  execs: MissionExec[]
}
Example response from schema 
{
  "execs": [
    {
      "id": "",
      "missionID": "",
      "kind": "feature",
      "targetID": "",
      "targetName": "",
      "startedAt": 0,
      "endedAt": 0,
      "status": "running",
      "heartbeatAt": 0,
      "sessionID": "",
      "error": "",
      "ok": false
    }
  ]
}

Generated from the response schema — field values are placeholders, the shape is real.

SDK example
mission.execs
ts 
import { createNikcliClient } from "@nikcli-ai/sdk/httpapi"

const client = createNikcliClient()
await client.mission.execs({
  ...
})
Try it

Schemas

The 20 schemas reachable from these endpoints. Each is shown one level deep; nested types link to their own entry below. Names ending in _2, _3 and so on are the OpenAPI emitter disambiguating same-named schemas declared by different HttpApi groups — they are distinct shapes, not duplicates.

MissionBooleanResult
boolean
MissionCreateInput
{
  name: string
  brief: string
  milestones: ({
    id: string
    name: string
    features: ({
      id: string
      name: string
      objective: string
      agent: string
      model?: string | null
      tokenBudget?: 
        | 
        | number
        | "Infinity" | "-Infinity" | "NaN"
        | null
      dependsOn?: string[] | null
      status?: 
        | 
        | "pending"
        | "running"
        | "done"
        | "blocked"
        | "skipped"
        | "error"
        | null
      error?: string | null
    })[]
    validation?: 
      | "scrutiny" | "user-test" | "none"
      | null
    status?: 
      | 
      | "pending"
      | "running"
      | "validating"
      | "done"
      | "blocked"
      | null
  })[]
  models?: 
    | {
    worker?: string | null
    validation?: string | null
    orchestrator?: string | null
  }
    | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  sandbox?: boolean | null
  worktree?: 
    | {
    name: string
    branch?: string | null
    directory: string
  }
    | null
}
MissionDefinition
{
  id: string
  name: string
  brief: string
  milestones: MissionMilestone[]
  models: MissionModels
  timeoutMs?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  sandbox?: boolean
  worktree?: MissionWorktree
  status: 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
MissionExec
{
  id: string
  missionID: string
  kind: "feature" | "validation"
  targetID: string
  targetName: string
  startedAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  endedAt?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  status: 
    | "running"
    | "complete"
    | "error"
    | "timeout"
    | "cancelled"
    | "orphaned"
  heartbeatAt?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  sessionID?: string
  error?: string
  ok: boolean
}
MissionExecsOutput
{
  execs: MissionExec[]
}
MissionFeature
{
  id: string
  name: string
  objective: string
  agent: string
  model?: string
  tokenBudget?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  dependsOn: string[]
  status: 
    | "pending"
    | "running"
    | "done"
    | "blocked"
    | "skipped"
    | "error"
  error?: string
}
MissionFeatureMutateInput
{
  status?: 
    | 
    | "pending"
    | "running"
    | "done"
    | "blocked"
    | "skipped"
    | "error"
    | null
  error?: string | null
  appendDependsOn?: string[] | null
}
MissionGenerateInput
{
  description: string
  model?: string
  agent?: string
  sessionID?: string
}
MissionGetOutput
{
  mission: MissionDefinition
  runtime: MissionRuntime
}
MissionListOutput
{
  missions: MissionDefinition[]
  runtimes: MissionRuntime[]
}
MissionMilestone
{
  id: string
  name: string
  features: MissionFeature[]
  validation: "scrutiny" | "user-test" | "none"
  status: 
    | "pending"
    | "running"
    | "validating"
    | "done"
    | "blocked"
}
MissionModels
{
  worker?: string
  validation?: string
  orchestrator?: string
}
MissionNotFound
{
  name: "NotFound"
  data: { [key: string]: unknown }
}
MissionRuntime
{
  missionID: string
  status: 
    | "idle"
    | "running"
    | "paused"
    | "error"
    | "cancelling"
  sessionID?: string
  currentMilestoneID?: string
  currentFeatureID?: string
  doneFeatures: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  totalFeatures: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
  lastError?: string
  lastRunAt?: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
MissionStartInput
{
  sessionID?: string | null
}
MissionTemplate
{
  id: string
  title: string
  description: string
  brief: string
}
MissionTemplatesOutput
{
  templates: MissionTemplate[]
}
MissionUpdateInput
{
  name: string
  brief: string
  milestones: ({
    id: string
    name: string
    features: ({
      id: string
      name: string
      objective: string
      agent: string
      model?: string | null
      tokenBudget?: 
        | 
        | number
        | "Infinity" | "-Infinity" | "NaN"
        | null
      dependsOn?: string[] | null
      status?: 
        | 
        | "pending"
        | "running"
        | "done"
        | "blocked"
        | "skipped"
        | "error"
        | null
      error?: string | null
    })[]
    validation?: 
      | "scrutiny" | "user-test" | "none"
      | null
    status?: 
      | 
      | "pending"
      | "running"
      | "validating"
      | "done"
      | "blocked"
      | null
  })[]
  models?: 
    | {
    worker?: string | null
    validation?: string | null
    orchestrator?: string | null
  }
    | null
  timeoutMs?: 
    | 
    | number
    | "Infinity" | "-Infinity" | "NaN"
    | null
  sandbox?: boolean | null
  worktree?: 
    | {
    name: string
    branch?: string | null
    directory: string
  }
    | null
  status?: 
    | 
    | "planning"
    | "ready"
    | "running"
    | "paused"
    | "frozen"
    | "complete"
    | "error"
    | null
  createdAt: 
    | number
    | "Infinity" | "-Infinity" | "NaN"
}
MissionValidationError
{
  name: "ValidationError"
  data: { [key: string]: unknown }
}
MissionWorktree
{
  name: string
  branch?: string
  directory: string
}