Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt

Use this file to discover all available pages before exploring further.

All mission endpoints require authentication and workspace context.

​
List All Missions (Workspace)

GET /api/v1/missions?workspace_id={workspaceId}
List all missions across the workspace. Query Parameters:
ParameterTypeDefaultDescription
workspace_idstringRequiredWorkspace ID
statusstring—Filter by status (e.g., IN_PROGRESS)
include_tasksstring"false"Set to "true" to include task details
limitinteger20Max items (1-100)
offsetinteger0Pagination offset
Response: 200 OK 
[
  {
    "id": "mission_abc",
    "workspace_id": "ws_123",
    "crew_id": "crew_456",
    "lead_agent_id": "agent_789",
    "lead_agent_name": "Tech Lead",
    "lead_agent_slug": "tech-lead",
    "trace_id": "mission-cm1abc123",
    "title": "Implement user authentication",
    "description": "Add JWT-based auth with refresh tokens",
    "status": "IN_PROGRESS",
    "plan": "1. Create auth middleware\n2. Add login endpoint...",
    "workflow_template": null,
    "total_token_count": 15000,
    "total_estimated_cost": 0.45,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z",
    "completed_at": null,
    "task_stats": {
      "total": 4,
      "pending": 1,
      "blocked": 0,
      "in_progress": 1,
      "completed": 2,
      "failed": 0,
      "skipped": 0,
      "awaiting_approval": 0
    },
    "tasks": []
  }
]

​
List Crew Missions

GET /api/v1/crews/{crewId}/missions?workspace_id={workspaceId}
Query Parameters:
ParameterTypeDefaultDescription
statusstring—Filter by status
limitinteger20Max items (1-100)
offsetinteger0Pagination offset
Response: 200 OK — array of mission objects with task_stats.

​
Create Mission

POST /api/v1/crews/{crewId}/missions?workspace_id={workspaceId}
Auth: OWNER, ADMIN, or MANAGER role Request Body:
FieldTypeRequiredDescription
titlestringYesMission title
descriptionstringNoMission description
lead_agent_idstringYesID of the LEAD agent in the crew
workflow_templatestringNoWorkflow template ID to use
{
  "title": "Implement user authentication",
  "description": "Add JWT-based auth with refresh tokens",
  "lead_agent_id": "agent_789"
}
The lead agent must exist in the specified crew and have the LEAD role. Response: 201 Created — mission object with status PLANNING.
StatusCondition
400Missing title, missing/invalid lead_agent_id, agent not LEAD role
403Insufficient role
WebSocket events: mission.created on crew:{crewId}, mission.updated on workspace:{workspaceId}

​
Get Mission

GET /api/v1/crews/{crewId}/missions/{missionId}?workspace_id={workspaceId}
Returns the mission with all tasks and task stats. Response: 200 OK 
{
  "id": "mission_abc",
  "title": "Implement user authentication",
  "status": "IN_PROGRESS",
  "tasks": [
    {
      "id": "task_001",
      "mission_id": "mission_abc",
      "assigned_agent_id": "agent_dev1",
      "agent_name": "Backend Dev",
      "agent_slug": "backend-dev",
      "title": "Create auth middleware",
      "description": "Implement JWT validation middleware",
      "status": "COMPLETED",
      "task_order": 1,
      "depends_on": "[]",
      "iteration": 1,
      "max_iterations": 3,
      "result_summary": "Created middleware with token validation",
      "output_path": "/workspace/internal/auth/middleware.go",
      "error_message": null,
      "assignment_id": "assign_abc",
      "token_count": 5000,
      "estimated_cost": 0.15,
      "started_at": "2024-01-15T10:05:00Z",
      "completed_at": "2024-01-15T10:15:00Z",
      "duration_ms": 600000,
      "confidence": 0.95,
      "needs_review": false,
      "handoff_context": null,
      "evaluation_status": "PASS",
      "evaluation_notes": null,
      "approval_required": false,
      "approval_status": null,
      "approved_by": null,
      "approved_at": null,
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:15:00Z"
    }
  ],
  "task_stats": { ... }
}
StatusCondition
404Mission not found

​
Update Mission

PATCH /api/v1/crews/{crewId}/missions/{missionId}?workspace_id={workspaceId}
Auth: OWNER, ADMIN, or MANAGER role Request Body: All fields optional.
FieldTypeDescription
titlestringMission title
descriptionstringMission description
planstringMission plan (markdown)
statusstringNew status (must be a valid transition)
Status Transitions:
FromAllowed To
PLANNINGIN_PROGRESS, CANCELLED
IN_PROGRESSREVIEW, FAILED, CANCELLED
REVIEWCOMPLETED, IN_PROGRESS, FAILED, CANCELLED
When status changes to COMPLETED, FAILED, or CANCELLED, completed_at is automatically set. Response: 200 OK — updated mission object.
StatusCondition
400Invalid status transition
404Mission not found

​
Delete Mission

DELETE /api/v1/crews/{crewId}/missions/{missionId}?workspace_id={workspaceId}
Only missions in PLANNING or CANCELLED status can be deleted (hard delete). Auth: OWNER, ADMIN, or MANAGER role Response: 204 No Content
StatusCondition
400Mission is not in PLANNING or CANCELLED status
404Mission not found

​
Start Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/start?workspace_id={workspaceId}
Transitions a PLANNING mission to IN_PROGRESS and starts the MissionEngine. Validates the task dependency DAG before starting. Uses atomic compare-and-swap to prevent concurrent start races. Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK 
{
  "id": "mission_abc",
  "status": "IN_PROGRESS"
}
StatusCondition
400Mission not in PLANNING state, or invalid task DAG
404Mission not found
409Mission was already started by another request
500MissionEngine failed to start (rolls back to PLANNING)

​
Restart Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/restart?workspace_id={workspaceId}
Restarts a COMPLETED, FAILED, or CANCELLED mission. Resets non-COMPLETED tasks (PENDING if dependencies allow, BLOCKED otherwise), increments their iteration, clears errors, and moves the mission back to PLANNING (call start afterwards to dispatch). (internal/api/task_state.go:14) Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK 
{ "id": "mission_abc", "status": "PLANNING" }
StatusCondition
404Mission not found
409Mission is not in a terminal state (COMPLETED/FAILED/CANCELLED)

​
Resume Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/resume?workspace_id={workspaceId}
Resumes a FAILED mission from the point of failure. The handler atomically claims the mission into RESUMING, resets the FAILED/AWAITING_APPROVAL tasks plus their downstream dependents, validates the DAG, and re-engages the MissionEngine. COMPLETED tasks are preserved. (internal/api/task_state.go:103) Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK
StatusCondition
400No failed tasks to resume from, or invalid DAG
404Mission not found
409Mission is not currently FAILED

​
Clone Mission

POST /api/v1/crews/{crewId}/missions/{missionId}/clone?workspace_id={workspaceId}
Creates a copy of the mission with all its tasks, resetting statuses to PLANNING/PENDING (or BLOCKED if the cloned task carries dependencies). Auth: OWNER, ADMIN, or MANAGER role Response: 201 Created 
{ "id": "mission_new", "status": "PLANNING" }
The handler returns the new mission id and status only; fetch GET /api/v1/crews/{crewId}/missions/{newId} for the full mission object (internal/api/task_state.go:472).

​
Create Task

POST /api/v1/crews/{crewId}/missions/{missionId}/tasks?workspace_id={workspaceId}
Add a task to a mission. Auth: OWNER, ADMIN, or MANAGER role Request Body: (internal/api/task_handler.go:42)
FieldTypeRequiredDefaultDescription
titlestringYes—Task title
descriptionstringNonullTask description
assigned_agent_idstringNonullAgent to assign to
task_orderintegerNo0Position in task list
depends_onstring[]No[]Array of task IDs this depends on
max_iterationsintegerNonullMax retry iterations
Tasks can only be added to missions in PLANNING or IN_PROGRESS state. If any dependency task is not COMPLETED, the new task is created with status BLOCKED; otherwise PENDING. Response: 201 Created

​
Update Task

PATCH /api/v1/crews/{crewId}/missions/{missionId}/tasks/{taskId}?workspace_id={workspaceId}
Request Body: All fields optional. (internal/api/task_handler.go:146)
FieldTypeDescription
titlestringTask title (PENDING/BLOCKED only)
descriptionstringTask description (PENDING/BLOCKED only)
assigned_agent_idstringReassign to a different agent
statusstringNew status (valid transition required)
depends_onstringJSON-encoded dependency task IDs (PENDING/BLOCKED only)
result_summarystringResult summary text
error_messagestringError message text
output_pathstringOutput file path
token_countintegerToken usage
estimated_costnumberEstimated cost in USD
status and depends_on cannot be set in the same request — the handler returns 400 with “Cannot update status and depends_on in the same request” (internal/api/task_handler.go:359). task_order, max_iterations, and approval_required are not currently mutable through this endpoint. Task Status Transitions:
FromAllowed To
PENDINGIN_PROGRESS, SKIPPED
BLOCKEDPENDING, SKIPPED
IN_PROGRESSCOMPLETED, FAILED, SKIPPED
Response: 200 OK

​
Mission Metrics

GET /api/v1/mission-metrics?workspace_id={workspaceId}
Aggregated mission metrics for the workspace, covering the last 24 hours. Response: 200 OK 
{
  "total_missions": 45,
  "active_missions": 3,
  "completed_24h": 8,
  "failed_24h": 1,
  "total_tokens_24h": 125000,
  "total_cost_24h": 3.75,
  "avg_completion_time_ms": 180000,
  "tasks_completed_24h": 24,
  "tasks_failed_24h": 2
}

​
Mission Statuses

StatusDescription
PLANNINGLead is analyzing and creating task breakdown
IN_PROGRESSAgents are working on tasks
REVIEWAll tasks done, lead is reviewing results
COMPLETEDSuccessfully finished
FAILEDUnresolvable problem encountered
CANCELLEDCancelled by user or system

​
Task Statuses

StatusDescription
PENDINGNot yet started, waiting for dependencies
BLOCKEDBlocked by unfinished dependency tasks
IN_PROGRESSAgent is currently working on it
COMPLETEDSuccessfully finished
FAILEDAgent failed the task
SKIPPEDManually skipped
AWAITING_APPROVALWaiting for human approval