Issues - Crewship

Issues are crew-scoped tracker items: each carries a human-readable identifier (e.g. ENG-42), a status flow, and lifecycle operations for agent execution. Beyond CRUD, the API covers comments, relations, an activity log, workspace labels, and projects that group issues with tracking metadata. Under the hood, issues are stored in the missions table with mission_type = 'issue' — they share infrastructure with missions but keep their own status flow, identifiers, and lifecycle.

All issue endpoints require authentication and workspace context.

Endpoints

Method	Endpoint	Purpose
`GET`	`/api/v1/issues`	List issues across a workspace
`GET`	`/api/v1/issues/{identifier}`	Get an issue by identifier (workspace-wide)
`POST`	`/api/v1/crews/{crewId}/issues`	Create an issue
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}`	Get an issue within a crew
`PATCH`	`/api/v1/crews/{crewId}/issues/{identifier}`	Update an issue
`DELETE`	`/api/v1/crews/{crewId}/issues/{identifier}`	Delete an issue
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/start`	Start issue execution
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/stop`	Stop a running issue
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/review`	Submit a review decision
`PATCH`	`/api/v1/issues/bulk`	Bulk-update up to 100 issues
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/subtasks`	List an issue’s sub-issues
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/activity`	List an issue’s activity log
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/runs`	List an issue’s agent task-runs
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/comments`	List comments on an issue
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/comments`	Add a comment
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/relations`	List relations
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/relations`	Create a relation
`DELETE`	`/api/v1/relations/{relationId}`	Delete a relation
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/code-links`	List linked pull requests
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/code-links`	Attach a pull request / merge request
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/code-links/{linkId}/refresh`	Re-fetch a link’s state
`DELETE`	`/api/v1/crews/{crewId}/issues/{identifier}/code-links/{linkId}`	Remove a link
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/attachments`	List attached files
`POST`	`/api/v1/crews/{crewId}/issues/{identifier}/attachments`	Attach a file
`GET`	`/api/v1/crews/{crewId}/issues/{identifier}/attachments/{attachmentId}`	Download an attached file
`DELETE`	`/api/v1/crews/{crewId}/issues/{identifier}/attachments/{attachmentId}`	Remove an attached file
`GET`	`/api/v1/labels`	List workspace labels
`POST`	`/api/v1/labels`	Create a label
`PATCH`	`/api/v1/labels/{labelId}`	Update a label
`DELETE`	`/api/v1/labels/{labelId}`	Delete a label
`GET`	`/api/v1/projects`	List projects
`POST`	`/api/v1/projects`	Create a project
`GET`	`/api/v1/projects/{projectId}`	Get a project
`PATCH`	`/api/v1/projects/{projectId}`	Update a project
`DELETE`	`/api/v1/projects/{projectId}`	Delete a project
`GET`	`/api/v1/projects/{projectId}/stats`	Project breakdown stats
`GET`	`/api/v1/projects/{projectId}/milestones`	List project milestones
`POST`	`/api/v1/projects/{projectId}/milestones`	Create a project milestone
`PATCH`	`/api/v1/milestones/{milestoneId}`	Update a project milestone
`DELETE`	`/api/v1/milestones/{milestoneId}`	Delete a project milestone

Issues CRUD

Create, read, update, and delete issues. Most write operations require OWNER, ADMIN, or MANAGER role and emit a WebSocket event on workspace:{workspaceId}.

List Issues (Workspace)

GET /api/v1/issues?workspace_id={workspaceId}

Returns issues across the workspace with filtering, sorting, and pagination. Query Parameters:

Parameter	Type	Default	Description
`workspace_id`	string	Required	Workspace ID
`mission_type`	string	`"issue"`	Filter by type (`"issue"` or `"mission"`)
`status`	string	—	Comma-separated status filter (e.g., `TODO,IN_PROGRESS`)
`priority`	string	—	Comma-separated priority filter (e.g., `urgent,high`)
`project_id`	string	—	Filter by project
`crew_id`	string	—	Filter by crew
`assignee_id`	string	—	Filter by assignee
`label`	string	—	Filter by label name
`search`	string	—	Search in title (LIKE match)
`sort`	string	`"created_at"`	Sort column: `created_at`, `updated_at`, `priority`, `sort_order`
`limit`	integer	`50`	Max items (1-100)
`offset`	integer	`0`	Pagination offset

Response: 200 OK

[
  {
    "id": "issue_abc",
    "workspace_id": "ws_123",
    "crew_id": "crew_456",
    "crew_name": "Engineering",
    "crew_slug": "engineering",
    "number": 42,
    "identifier": "ENG-42",
    "title": "Fix authentication token refresh",
    "description": "Tokens are not being refreshed before expiry",
    "status": "TODO",
    "priority": "high",
    "assignee_type": "agent",
    "assignee_id": "agent_789",
    "assignee_name": "Backend Dev",
    "created_by": {
      "type": "agent",
      "id": "agent_789",
      "name": "Backend Dev"
    },
    "authored_via": "agent_tool_call",
    "due_date": "2024-02-01",
    "sort_order": 0.0,
    "mission_type": "issue",
    "lead_agent_id": "agent_lead",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "completed_at": null,
    "labels": [
      {
        "id": "label_abc",
        "name": "bug",
        "color": "#ef4444",
        "label_group": null
      }
    ],
    "project_id": "proj_123",
    "comment_count": 3
  }
]

Response fields

Field	Type	Description
`id`	string	Issue ID (same as underlying mission ID)
`workspace_id`	string	Workspace ID
`crew_id`	string	Crew ID
`crew_name`	string	Crew display name
`crew_slug`	string	Crew slug
`number`	integer	Sequential issue number within the crew
`identifier`	string	Human-readable identifier (e.g., `ENG-42`)
`title`	string	Issue title
`description`	string?	Issue description
`status`	string	Current status
`priority`	string	Priority level
`assignee_type`	string?	`"user"` or `"agent"`
`assignee_id`	string?	Assignee ID
`assignee_name`	string?	Resolved assignee name
`created_by`	object?	Who created the issue: `{type, id, name}` where `type` is `"user"` (created via the API/UI) or `"agent"` (created by an agent tool call). `name` is resolved at read time like `assignee_name`. Omitted on issues that predate creator attribution
`authored_via`	string?	Creation channel: `"user_api"` (human via API/UI/slash command) or `"agent_tool_call"` (agent via sidecar). Omitted on legacy issues
`due_date`	string?	Due date
`sort_order`	number	Manual sort order for board views
`mission_type`	string	Always `"issue"` for issues
`lead_agent_id`	string	Crew’s lead agent ID
`labels`	array	Array of label objects
`project_id`	string?	Parent project ID
`estimate`	integer?	Effort/points estimate
`parent_issue_id`	string?	Parent issue ID for sub-issues
`milestone_id`	string?	Associated milestone ID
`sub_issues_count`	integer	Count of child issues with `parent_issue_id` = this issue
`routine_id`	string?	Bound pipeline ID for `/run-routine` (omitted if unbound)
`routine_slug`	string?	Slug of the bound pipeline (denormalized for UI)
`routine_name`	string?	Name of the bound pipeline (denormalized for UI)
`comment_count`	integer	Number of comments
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp
`completed_at`	string?	When issue was completed/cancelled/marked duplicate

Get Issue (Workspace-scoped)

GET /api/v1/issues/{identifier}?workspace_id={workspaceId}

Get an issue by its identifier (e.g., ENG-42) across the entire workspace. No crew ID needed. Request: identifier is required; workspace_id selects the workspace. No request body. Response: 200 OK — full issue object with labels and comment count.

Status	Condition
`404`	Issue not found

Create Issue

POST /api/v1/crews/{crewId}/issues?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role The crew must have a LEAD agent. The issue identifier is auto-generated from the crew’s issue_prefix (or first 3 characters of the slug) and an auto-incrementing counter. Request Body:

Field	Type	Required	Default	Description
`title`	string	Yes	—	Issue title
`description`	string	No	`null`	Issue description
`priority`	string	No	`"none"`	Priority: `none`, `low`, `medium`, `high`, `urgent`
`assignee_type`	string	No	`null`	`"user"` or `"agent"`
`assignee_id`	string	No	`null`	Assignee ID
`due_date`	string	No	`null`	Due date (YYYY-MM-DD)
`project_id`	string	No	`null`	Parent project ID
`estimate`	integer	No	`null`	Effort/points estimate
`parent_issue_id`	string	No	`null`	Parent issue ID for sub-issues (validated against current workspace)
`milestone_id`	string	No	`null`	Associated milestone ID
`labels`	string[]	No	`[]`	Array of label IDs to attach
`routine_id`	string	No	`null`	Pipeline ID to bind for `/run-routine` (must exist in workspace)
`routine_inputs`	object	No	`{}`	JSON object of routine input values; rejected with 400 if set without `routine_id`

{
  "title": "Fix authentication token refresh",
  "description": "Tokens are not being refreshed before expiry",
  "priority": "high",
  "assignee_type": "agent",
  "assignee_id": "agent_789",
  "labels": ["label_bug"]
}

Response: 201 Created — issue object with generated number and identifier.

Status	Condition
`400`	Missing title, crew has no lead agent, `routine_inputs` set without `routine_id`, `routine_id`/`parent_issue_id` not in workspace, or `routine_inputs` not valid JSON
`403`	Insufficient role
`404`	Crew not found

WebSocket event: issue.created on workspace:{workspaceId}

Get Issue (Crew-scoped)

GET /api/v1/crews/{crewId}/issues/{identifier}?workspace_id={workspaceId}

Get an issue by its identifier within a specific crew. Includes labels and comment count. Request: crewId and identifier are required path parameters; workspace_id selects the workspace. No request body. Response: 200 OK — full issue object.

Update Issue

PATCH /api/v1/crews/{crewId}/issues/{identifier}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body: All fields optional.

Field	Type	Description
`title`	string	Issue title
`description`	string	Issue description
`status`	string	New status (must be valid transition)
`priority`	string	Priority level
`assignee_type`	string	`"user"` or `"agent"`
`assignee_id`	string	Assignee ID
`due_date`	string	Due date
`project_id`	string	Project ID (empty string to unlink)
`estimate`	integer \| null	Effort/points estimate; `null` clears it, a non-number is a `400`
`parent_issue_id`	string	Parent issue ID; empty string unlinks; cannot equal the issue itself
`milestone_id`	string	Milestone ID; empty string unlinks
`sort_order`	number	Manual sort order
`labels`	string[]	Replace all labels with this set of label IDs
`routine_id`	string	Pipeline ID to bind; empty string clears binding (also resets `routine_inputs`)
`routine_inputs`	object	Full-replacement JSON object for routine inputs

Status Transitions:

From	Allowed To
`BACKLOG`	`TODO`, `IN_PROGRESS`, `CANCELLED`, `DUPLICATE`
`TODO`	`IN_PROGRESS`, `BACKLOG`, `CANCELLED`, `DUPLICATE`
`IN_PROGRESS`	`REVIEW`, `DONE`, `FAILED`, `CANCELLED`, `TODO`, `DUPLICATE`
`REVIEW`	`DONE`, `TODO`, `IN_PROGRESS`, `FAILED`, `CANCELLED`, `DUPLICATE`
`DONE`	`BACKLOG`
`FAILED`	`BACKLOG`, `TODO`, `IN_PROGRESS`
`CANCELLED`	`BACKLOG`, `TODO`
`DUPLICATE`	(none — terminal)

When status changes to DONE, CANCELLED, or DUPLICATE, completed_at is automatically set. Significant changes (status, assignee, priority) are logged as activity entries. Response: 200 OK — updated issue object.

Status	Condition
`400`	Invalid status transition, no fields to update, `parent_issue_id` equals issue itself, `parent_issue_id`/`routine_id` not in workspace, or `routine_inputs` not valid JSON
`404`	Issue not found

WebSocket event: issue.updated on workspace:{workspaceId}

Delete Issue

DELETE /api/v1/crews/{crewId}/issues/{identifier}?workspace_id={workspaceId}

Hard-deletes the issue. Only issues in BACKLOG or CANCELLED status can be deleted.

Request: crewId and identifier are required path parameters; workspace_id selects the workspace. No request body. Auth: OWNER, ADMIN, or MANAGER role Response: 204 No Content

Status	Condition
`400`	Issue is not in BACKLOG or CANCELLED status
`404`	Issue not found

WebSocket event: issue.deleted on workspace:{workspaceId}

Lifecycle Actions

Drive an issue through agent execution: start, stop, and review.

Start Issue

POST /api/v1/crews/{crewId}/issues/{identifier}/start?workspace_id={workspaceId}

Starts execution of a BACKLOG or TODO issue. The issue must have an assignee. This:

Creates a synthetic chat session for the mission
Creates or resets tasks (resets existing tasks to PENDING for re-runs)
Transitions status to IN_PROGRESS
Starts the MissionEngine asynchronously

Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK

{
  "status": "IN_PROGRESS",
  "identifier": "ENG-42"
}

Status	Condition
`400`	Issue not in BACKLOG/TODO, or no assignee
`404`	Issue not found
`409`	Issue was already started by another request

WebSocket event: issue.started on workspace:{workspaceId}

Stop Issue

POST /api/v1/crews/{crewId}/issues/{identifier}/stop?workspace_id={workspaceId}

Stops a running issue. Cancels all running/pending tasks and sets status to CANCELLED. Only issues in IN_PROGRESS or REVIEW status can be stopped.

Request: crewId and identifier are required path parameters; workspace_id selects the workspace. No request body. Auth: OWNER, ADMIN, or MANAGER role Response: 200 OK

{
  "status": "CANCELLED",
  "identifier": "ENG-42"
}

Status	Condition
`400`	Issue not in IN_PROGRESS or REVIEW status
`404`	Issue not found

Review Issue

POST /api/v1/crews/{crewId}/issues/{identifier}/review?workspace_id={workspaceId}

Submit a review decision for an issue in REVIEW or IN_PROGRESS status. Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`action`	string	Yes	`"approve"` or `"request_changes"`
`comment`	string	No	Review comment
`reassign_to`	string	No	Agent slug to reassign to (for `request_changes`)

{
  "action": "request_changes",
  "comment": "The error handling needs improvement",
  "reassign_to": "backend-dev"
}

approve: Transitions issue to DONE, adds approval comment and activity
request_changes: Transitions issue to TODO, optionally reassigns, adds comment and activity

Response: 200 OK

{
  "status": "ok",
  "action": "request_changes"
}

Status	Condition
`400`	Invalid action, or issue not in reviewable status
`404`	Issue not found

Bulk

Apply one set of field updates across many issues from the board/list multi-select toolbar.

Bulk Update

PATCH /api/v1/issues/bulk

Apply a single set of field updates to up to 100 issues at once. Used by the board/list views’ multi-select toolbar. Each issue is processed in its own statement — partial success is possible: a request touching 50 ids where 3 have invalid status transitions returns {"updated": 47} rather than rolling back. Auth: OWNER, ADMIN, or MANAGER role (create permission). Request Body:

Field	Type	Required	Description
`ids`	string[]	Yes	1-100 mission ids. Ids outside the caller’s workspace are skipped silently.
`updates.status`	string	No	New status. Invalid transitions are skipped per-issue (not 400). When `DONE`, `CANCELLED`, or `DUPLICATE`, `completed_at` is set automatically.
`updates.priority`	string	No	Priority level.
`updates.assignee_type`	string	No	`"user"` or `"agent"`.
`updates.assignee_id`	string	No	Assignee id.
`updates.project_id`	string	No	Project id; empty string unlinks.
`updates.labels`	string[]	No	Replace all labels on each issue with this set of label ids.

{
  "ids": ["issue_abc", "issue_def", "issue_ghi"],
  "updates": {
    "status": "TODO",
    "priority": "high",
    "labels": ["label_bug", "label_blocker"]
  }
}

Response: 200 OK

{ "updated": 3 }

Field	Type	Description
`updated`	integer	Count of issues that successfully applied at least one field. Issues whose `updates` resolved to a no-op are excluded.

Status	Condition
`400`	Invalid JSON, missing `ids`, or `ids` length > 100.
`403`	Caller lacks the `create` permission for the workspace.

When updated > 0, an issues.bulk_updated WebSocket event is broadcast on workspace:{workspaceId} with the count. Per-issue status changes additionally produce activity entries (status_changed, details suffixed with (bulk)).

Sub-issues

Issues can nest via parent_issue_id. List the children of one parent.

List Sub-issues

GET /api/v1/crews/{crewId}/issues/{identifier}/subtasks

Returns the children of one parent issue — rows where parent_issue_id equals the resolved parent id. Ordered by sort_order ASC, created_at ASC so the response matches the order operators see in the UI’s nested list. Path parameters:

Param	Description
`crewId`	Crew id (used to disambiguate identifiers across crews).
`identifier`	Human-readable identifier (e.g. `ENG-42`) or raw mission id of the parent.

Response: 200 OK — array of full issue objects matching the GET /api/v1/issues shape. Empty array (never null) when the parent has no sub-issues.

Status	Condition
`404`	Parent issue not found in the supplied crew + workspace.
`500`	DB read failure.

Activity

A read-only audit trail of significant issue changes.

List Activity

GET /api/v1/crews/{crewId}/issues/{identifier}/activity?workspace_id={workspaceId}

Returns the activity log for an issue (status changes, assignments, reviews). Limited to 50 most recent entries. Response: 200 OK

[
  {
    "id": "act_abc",
    "mission_id": "issue_123",
    "actor_type": "user",
    "actor_id": "user_456",
    "actor_name": "John Doe",
    "action": "status_changed",
    "details": "TODO -> IN_PROGRESS",
    "created_at": "2024-01-15T10:00:00Z"
  }
]

Activity Actions: created, status_changed, assignee_changed, priority_changed, description_changed, parent_changed, relation_added, code_link_added, code_link_removed, review_approved, review_changes_requested, task_completed, task_failed description_changed records that the description was rewritten, never the text itself — details carries only lengths (description updated (128 → 342 chars)). An issue description is unbounded user input, and an audit row is not a revision store; if you need the previous text, read the issue history in your own tooling before you PATCH. Every action above also writes a Crew Journal entry, which is what notifications are routed from — including the ones an agent produces through the internal API. A client that reads the activity list sees the same events a Slack/ntfy subscriber does.

Runs

The agent executions behind an issue. Issues run on the mission engine (not pipelines), so a “run” is a mission task backed by an assignments row.

List Runs

GET /api/v1/crews/{crewId}/issues/{identifier}/runs?workspace_id={workspaceId}

Lists the agent task-runs for an issue — each mission task joined to its assignments row (execution status, timing, result, error). Newest-first, capped at 100 rows. Request: crewId and identifier are required path parameters; workspace_id selects the workspace. No request body. Auth: any authenticated workspace member (read). Response: 200 OK — a JSON array (never null).

[
  {
    "id": "asg_abc",
    "status": "completed",
    "agent_name": "Backend Dev",
    "task": "Refresh token handling",
    "started_at": "2026-01-15T10:00:00Z",
    "ended_at": "2026-01-15T10:04:12Z",
    "duration_ms": 252000,
    "result_summary": "Patched refresh path and added a regression test.",
    "error_message": ""
  }
]

Field	Type	Description
`id`	string	Assignment (run) ID
`status`	string	Assignment status
`agent_name`	string?	Resolved name of the assigned agent (omitted when empty)
`task`	string?	Task text (omitted when empty)
`started_at`	string?	Start timestamp (omitted when empty)
`ended_at`	string?	Finish timestamp (omitted when empty)
`duration_ms`	integer	Elapsed time in ms; `0` when timing can’t be derived
`result_summary`	string?	Agent-authored result prose, truncated for the list (omitted when empty)
`error_message`	string?	Failure detail, truncated for the list (omitted when empty)

Status	Condition
`404`	Issue not found in the supplied crew + workspace

Comments

Threaded discussion on an issue, ordered oldest-first.

List Comments

GET /api/v1/crews/{crewId}/issues/{identifier}/comments?workspace_id={workspaceId}

Returns all comments on an issue, ordered by creation date ascending. Request: crewId and identifier are required path parameters; workspace_id selects the workspace. No request body. Response: 200 OK

[
  {
    "id": "comment_abc",
    "mission_id": "issue_123",
    "author_type": "user",
    "author_id": "user_456",
    "author_name": "John Doe",
    "body": "This looks good, just fix the edge case",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

Create Comment

POST /api/v1/crews/{crewId}/issues/{identifier}/comments?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`body`	string	Yes	Comment text

{
  "body": "This looks good, just fix the edge case"
}

Response: 201 Created — comment object with author_type: "user".

Relations

Link issues to one another (blocks, relates to, duplicate of). Relation types are flipped when viewed from the target side.

List Relations

GET /api/v1/crews/{crewId}/issues/{identifier}/relations?workspace_id={workspaceId}

Returns all relations for an issue. Relation types are flipped when viewed from the target side (e.g., blocks becomes blocked_by). Request: crewId and identifier are required path parameters; workspace_id selects the workspace. No request body. Response: 200 OK

[
  {
    "id": "rel_abc",
    "source_id": "issue_123",
    "target_id": "issue_456",
    "relation_type": "blocks",
    "target_identifier": "ENG-43",
    "target_title": "Deploy auth service",
    "target_status": "BACKLOG",
    "created_at": "2024-01-15T10:00:00Z"
  }
]

Create Relation

POST /api/v1/crews/{crewId}/issues/{identifier}/relations?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`target_identifier`	string	Yes	Target issue identifier (e.g., `ENG-43`)
`relation_type`	string	Yes	`blocks`, `blocked_by`, `relates_to`, or `duplicate_of`

{
  "target_identifier": "ENG-43",
  "relation_type": "blocks"
}

Internally, blocked_by is stored as blocks with source/target swapped for normalization. Response: 201 Created

Status	Condition
`400`	Invalid relation_type, self-relation
`404`	Source or target issue not found
`409`	Relation already exists

Delete Relation

DELETE /api/v1/relations/{relationId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request: relationId is a required path parameter and workspace_id selects the workspace. No request body. Response: 200 OK with {"status": "ok"}

Status	Condition
`404`	Relation not found

Code links

Attach the pull request / merge request that resolves an issue. The provider is recognised from the URL’s path grammar (/pull/<n> → GitHub, /-/merge_requests/<n> → GitLab), so github.com, gitlab.com and self-hosted instances of either all work. State is fetched through the provider’s REST API using a stored GITHUB / GITLAB credential — see Git links for how the credential is chosen and how private-network forges are allowed.

List code links

GET /api/v1/crews/{crewId}/issues/{identifier}/code-links?workspace_id={workspaceId}

Response: 200 OK

[
  {
    "id": "cmsezurje0003d5e624ad",
    "mission_id": "issue_123",
    "provider": "GITHUB",
    "host": "github.com",
    "owner": "acme",
    "repo": "thing",
    "number": 7,
    "kind": "pull_request",
    "url": "https://github.com/acme/thing/pull/7",
    "title": "Add the widget",
    "state": "OPEN",
    "author": "octocat",
    "source_branch": "feat/widget",
    "target_branch": "main",
    "remote_merged_at": null,
    "credential_id": "cred_abc",
    "last_synced_at": "2026-08-04T18:31:03Z",
    "last_sync_error": null
  }
]

state is OPEN, DRAFT, MERGED or CLOSED — normalised across both providers. A merged GitHub pull request reports closed with a merged_at; Crewship records it as MERGED.

Attach a code link

POST /api/v1/crews/{crewId}/issues/{identifier}/code-links?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`url`	string	Yes	The pull-request / merge-request web URL

{ "url": "https://github.com/acme/thing/pull/7" }

Response: 201 Created — the stored link, the same object shape List code links returns.

{
  "id": "cmsezurje0003d5e624ad",
  "mission_id": "issue_123",
  "provider": "GITHUB",
  "host": "github.com",
  "owner": "acme",
  "repo": "thing",
  "number": 7,
  "kind": "pull_request",
  "url": "https://github.com/acme/thing/pull/7",
  "title": "Add the widget",
  "state": "OPEN",
  "author": "octocat",
  "source_branch": "feat/widget",
  "target_branch": "main",
  "remote_merged_at": null,
  "credential_id": "cred_abc",
  "last_synced_at": "2026-08-04T18:31:03Z",
  "last_sync_error": null
}

The state is fetched before the row is written, so a 201 means the link was reachable. Errors are application/problem+json (RFC 7807) with a stable type URI under https://crewship.ai/problems/code-link/ and a code member, because several failures share a status:

Status	`code`	Condition
`400`	`invalid-body`	The request body is not valid JSON
`400`	`unsupported-url`	Not a recognised pull-request / merge-request URL
`403`	—	Caller lacks the MANAGER floor
`404`	`issue-not-found`	No such issue in this crew/workspace
`404`	`pull-request-not-found`	Provider returned 404 (or the credential cannot see a private repo)
`409`	`already-linked`	That pull request is already attached to this issue
`412`	`no-credential`	No ACTIVE credential for that provider can reach that host
`422`	`blocked-host`	The forge is on a private/internal address and the opt-in is off
`429`	`rate-limited`	Provider throttled; `Retry-After` is set when known
`502`	`credential-rejected`	Provider returned 401 — token revoked or expired
`502`	`credential-forbidden`	Token valid but lacks repository read access
`502`	`provider-unavailable`	Provider returned 5xx or did not answer
`502`	`cross-host-redirect`	The provider redirected off its own host; not followed, because the request carries a credential

Refresh a code link

POST /api/v1/crews/{crewId}/issues/{identifier}/code-links/{linkId}/refresh?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body: none. The link is addressed by the linkId path parameter; workspace_id is the only query parameter. Re-reads the link from its provider and returns the updated object. State is never polled in the background; this is the only refresh path. Response: 200 OK — the refreshed link, the same object shape List code links returns, with last_synced_at moved forward and last_sync_error cleared.

Status	`code`	Condition
`200`	—	Re-fetched; the row now reflects the provider
`403`	—	Caller lacks the MANAGER floor
`404`	`issue-not-found`	No such issue in this crew/workspace
`404`	`link-not-found`	No such link on this issue
`412`	`no-credential`	No ACTIVE credential for that provider can reach that host
`429`	`rate-limited`	Provider throttled; `Retry-After` is set when known
`502`	`credential-rejected` / `credential-forbidden` / `provider-unavailable`	The provider refused or did not answer

A failed refresh keeps the previously fetched state and records the reason on the row (last_sync_error), then returns the same problem document the attach path would.

Delete a code link

DELETE /api/v1/crews/{crewId}/issues/{identifier}/code-links/{linkId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body: none. The link is addressed by the linkId path parameter; workspace_id is the only query parameter. Response: 200 OK with {"status": "ok"} Hard delete — the row goes, the way a mission_relation does. Nothing about the pull request on the forge changes.

Status	`code`	Condition
`200`	—	Removed
`403`	—	Caller lacks the MANAGER floor
`404`	`link-not-found`	Link not found on this issue

Attachments

Attach files to an issue — a crash log, a screenshot, a repro bundle, a diff. Everything an agent working the issue needs to see and, before this surface existed, had to be pasted into a comment. Three properties are worth knowing before you use it:

The type is decided by the file’s extension, against an allowlist. The request’s own Content-Type is discarded. That header is chosen by whoever is uploading, and honouring it is how a stored file becomes stored XSS served from your own origin. Allowed today: .txt .log .md .csv .tsv .json .yaml .yml .toml .xml .diff .patch .png .jpg .jpeg .gif .webp .avif .pdf .zip .gz .tgz. .html, .svg and anything executable are absent deliberately, not by oversight.
Files are stored by content. Two issues carrying identical bytes share one stored copy, and attaching the same file to the same issue twice is the same attachment — the second call returns 200 with the existing record rather than 201 or 409, so a retry is safe. “The same file” means the same bytes under the same name: crash-before-fix.log and crash-after-fix.log can be byte-identical and mean opposite things, so both are attached and both get 201, sharing one stored copy.
The uploaded filename is a label, never a path. The stored location is derived entirely from the SHA-256 digest, so a filename of ../../../etc/passwd is recorded as passwd and the bytes land where every other attachment’s do.

Agents reach the same files through the sidecar — see Attachments an agent can read.

List attachments

GET /api/v1/crews/{crewId}/issues/{identifier}/attachments?workspace_id={workspaceId}

Auth: any workspace member (session or CLI token). The workspace is taken from the authenticated session, so an issue in another workspace is a 404. Request: workspace_id is the required workspace query parameter. No request body. Response: 200 OK — newest first.

[
  {
    "id": "cmsf1a2b30001d5e6aa11",
    "workspace_id": "ws_abc",
    "owner_type": "issue",
    "owner_id": "issue_123",
    "filename": "crash.log",
    "content_type": "text/plain; charset=utf-8",
    "size_bytes": 20481,
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "uploaded_by_user_id": "user_1",
    "uploaded_by_agent_id": null,
    "uploaded_by_name": "Ada Lovelace",
    "created_at": "2026-08-06T19:22:41Z"
  }
]

sha256 is part of the contract: it lets a client verify what it downloaded, and lets an agent decide it has already read this exact file. The on-disk storage key is deliberately not exposed.

Status	Condition
`200`	Listed (possibly empty)
`400`	No workspace resolved for the caller
`404`	Issue not found in this workspace

Upload an attachment

POST /api/v1/crews/{crewId}/issues/{identifier}/attachments?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body: multipart/form-data with one part.

Field	Type	Required	Description
`file`	file	Yes	The file. Maximum 25 MiB. Its extension must be on the allowlist above

curl -X POST \
  -H "Authorization: Bearer $CREWSHIP_TOKEN" \
  -F "file=@./crash.log" \
  "https://crewship.example.com/api/v1/crews/crew_1/issues/ENG-4/attachments?workspace_id=ws_abc"

Response: 201 Created — the stored record, the same object shape List attachments returns. 200 OK instead of 201 means this exact file — these bytes, under this filename — was already attached to this issue: no second record was created, no second timeline entry was written, and the returned object is the one that already existed. The same bytes under a different filename are a different attachment and get 201.

Status	Condition
`201`	Attached
`200`	Already attached — the same bytes under the same filename, on the same issue
`400`	Malformed multipart form, missing `file` part, or a filename that sanitises to nothing
`403`	Caller lacks the MANAGER floor
`404`	Issue not found in this workspace
`413`	Larger than 25 MiB
`415`	Extension not on the allowlist — the response lists what is allowed
`503`	This instance has no storage provider configured

Download an attachment

GET /api/v1/crews/{crewId}/issues/{identifier}/attachments/{attachmentId}?workspace_id={workspaceId}

Auth: any workspace member. Request: workspace_id is the required workspace query parameter. The file is addressed by the attachmentId path parameter. No request body. Response: 200 OK — the raw bytes, with three headers that matter:

Header	Value
`Content-Type`	The type Crewship resolved from the extension, never the uploader’s
`X-Content-Type-Options`	`nosniff`
`Content-Disposition`	`attachment; filename="crash.log"`

An attachment belonging to a different issue — even one in the same workspace — is a 404 through this issue’s URL, not a 403.

Status	Condition
`200`	The file
`404`	Not found on this issue, or its stored bytes are missing (for example after a metadata-only restore)
`503`	This instance has no storage provider configured

Delete an attachment

DELETE /api/v1/crews/{crewId}/issues/{identifier}/attachments/{attachmentId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body: none. The file is addressed by the attachmentId path parameter; workspace_id is the only query parameter. Response: 200 OK with {"status": "ok"} Hard delete of the record, and of the stored bytes — but the bytes only when no other issue, comment or chat in this workspace still references them. Removing a file from one issue never removes it from another that carries the same file.

Status	Condition
`200`	Removed
`403`	Caller lacks the MANAGER floor
`404`	Not found on this issue

Labels

Labels are workspace-scoped and can be attached to any issue.

List Labels

GET /api/v1/labels?workspace_id={workspaceId}

Request: workspace_id is the required workspace query parameter. No request body. Response: 200 OK

[
  {
    "id": "label_abc",
    "name": "bug",
    "color": "#ef4444",
    "label_group": null
  }
]

Create Label

POST /api/v1/labels?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request: workspace_id selects the workspace. The JSON body requires name and color; label_group is optional.

Field	Type	Required	Description
`name`	string	Yes	Label name
`color`	string	Yes	Color hex code
`label_group`	string	No	Grouping category

Response: 201 Created

Update Label

PATCH /api/v1/labels/{labelId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request: labelId is required, workspace_id selects the workspace, and the JSON body may contain name, color, and/or label_group. All fields optional: name, color, label_group. Response: 200 OK — updated label.

Status	Condition
`400`	No fields to update
`404`	Label not found

Delete Label

DELETE /api/v1/labels/{labelId}?workspace_id={workspaceId}

Auth: OWNER or ADMIN role Request: labelId is a required path parameter and workspace_id selects the workspace. No request body. Response: 204 No Content

Status	Condition
`404`	Label not found

Projects

Projects group related issues together with tracking metadata.

List Projects

GET /api/v1/projects?workspace_id={workspaceId}

Query Parameters:

Parameter	Type	Description
`status`	string	Comma-separated status filter
`sort`	string	Sort column: `name` (default), `created_at`, `updated_at`

Response: 200 OK

[
  {
    "id": "proj_abc",
    "workspace_id": "ws_123",
    "name": "Q1 Backend Overhaul",
    "slug": "q1-backend-overhaul",
    "description": "Major backend refactoring",
    "icon": "rocket",
    "color": "blue",
    "status": "started",
    "priority": "high",
    "health": "on_track",
    "lead_type": "user",
    "lead_id": "user_123",
    "lead_name": "John Doe",
    "start_date": "2024-01-01",
    "target_date": "2024-03-31",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "issue_count": 12,
    "done_count": 8,
    "progress": 66
  }
]

Create Project

POST /api/v1/projects?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role

Field	Type	Required	Default	Description
`name`	string	Yes	—	Project name
`description`	string	No	`null`	Description
`icon`	string	No	`null`	Lucide icon name
`color`	string	No	`"blue"`	Palette color
`status`	string	No	`"backlog"`	Project status
`priority`	string	No	`"none"`	Priority level
`lead_type`	string	No	`null`	`"user"` or `"agent"`
`lead_id`	string	No	`null`	Lead person/agent ID
`start_date`	string	No	`null`	Start date
`target_date`	string	No	`null`	Target date

Response: 201 Created

Get Project

GET /api/v1/projects/{projectId}?workspace_id={workspaceId}

Response: 200 OK — project with computed issue_count, done_count, and progress fields.

Update Project

PATCH /api/v1/projects/{projectId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role All fields optional: name, description, icon, color, status, priority, health, lead_type, lead_id, start_date, target_date. Response: 200 OK — updated project.

Delete Project

DELETE /api/v1/projects/{projectId}?workspace_id={workspaceId}

Auth: OWNER or ADMIN role

Unlinks all issues from the project before deletion.

Response: 204 No Content

Project Stats

GET /api/v1/projects/{projectId}/stats?workspace_id={workspaceId}

Returns breakdown data: counts by status, by assignee, by label, and crew list. Response: 200 OK

{
  "total_issues": 12,
  "completed_issues": 8,
  "by_status": {
    "BACKLOG": 1,
    "TODO": 2,
    "IN_PROGRESS": 1,
    "DONE": 8
  },
  "by_assignee": [
    {
      "agent_id": "agent_abc",
      "agent_name": "Backend Dev",
      "total": 5,
      "completed": 4
    }
  ],
  "by_label": [
    {
      "label_name": "bug",
      "color": "#ef4444",
      "count": 3
    }
  ],
  "crews": ["crew_abc"]
}

Milestones

Milestones belong to projects and expose progress counts for the issues linked to them. All routes are workspace-scoped through the project or milestone.

List Milestones

GET /api/v1/projects/{projectId}/milestones?workspace_id={workspaceId}

Request: projectId is a required path parameter and workspace_id selects the workspace. No request body. Returns 200 OK with an array ordered by position, then creation time. Each item contains id, project_id, name, nullable description and target_date, status, position, issue_count, done_count, created_at, and updated_at. A project outside the workspace returns 404.

Create Milestone

POST /api/v1/projects/{projectId}/milestones?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role. The request requires name; optional fields are description, target_date, and status (default active). The response is 201 Created with the full milestone object and its next position.

Update Milestone

PATCH /api/v1/milestones/{milestoneId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role. Any of name, description, target_date, status, and position may be updated; at least one field is required. Returns 200 OK with the updated milestone, or 400 for invalid JSON/no fields and 404 when it is not in the workspace.

Delete Milestone

DELETE /api/v1/milestones/{milestoneId}?workspace_id={workspaceId}

Auth: OWNER or ADMIN role. Returns 204 No Content, or 404 when the milestone is not in the workspace.

Reference

Issue Statuses

Status	Description
`BACKLOG`	Not yet prioritized
`TODO`	Planned for work
`IN_PROGRESS`	Agent is actively working
`REVIEW`	Waiting for human review
`DONE`	Completed and approved
`FAILED`	Agent encountered unresolvable error
`CANCELLED`	Cancelled by user
`DUPLICATE`	Marked as duplicate (no transitions out)

Priority Levels

Value	Description
`none`	No priority set
`low`	Low priority
`medium`	Medium priority
`high`	High priority
`urgent`	Urgent priority

​Endpoints

​Issues CRUD

​List Issues (Workspace)

​Get Issue (Workspace-scoped)

​Create Issue

​Get Issue (Crew-scoped)

​Update Issue

​Delete Issue

​Lifecycle Actions

​Start Issue

​Stop Issue

​Review Issue

​Bulk

​Bulk Update

​Sub-issues

​List Sub-issues

​Activity

​List Activity

​Runs

​List Runs

​Comments

​List Comments

​Create Comment

​Relations

​List Relations

​Create Relation

​Delete Relation

​Code links

​List code links

​Attach a code link

​Refresh a code link

​Delete a code link

​Attachments

​List attachments

​Upload an attachment

​Download an attachment

​Delete an attachment

​Labels

​List Labels

​Create Label

​Update Label

​Delete Label

​Projects

​List Projects

​Create Project

​Get Project

​Update Project

​Delete Project

​Project Stats

​Milestones

​List Milestones

​Create Milestone

​Update Milestone

​Delete Milestone

​Reference

​Issue Statuses

​Priority Levels

Endpoints

Issues CRUD

List Issues (Workspace)

Get Issue (Workspace-scoped)

Create Issue

Get Issue (Crew-scoped)

Update Issue

Delete Issue

Lifecycle Actions

Start Issue

Stop Issue

Review Issue

Bulk

Bulk Update

Sub-issues

List Sub-issues

Activity

List Activity

Runs

List Runs

Comments

List Comments

Create Comment

Relations

List Relations

Create Relation

Delete Relation

Code links

List code links

Attach a code link

Refresh a code link

Delete a code link

Attachments

List attachments

Upload an attachment

Download an attachment

Delete an attachment

Labels

List Labels

Create Label

Update Label

Delete Label

Projects

List Projects

Create Project

Get Project

Update Project

Delete Project

Project Stats

Milestones

List Milestones

Create Milestone

Update Milestone

Delete Milestone

Reference

Issue Statuses

Priority Levels