Issues

Endpoints for the full issue lifecycle — creating, updating, checking out, commenting, managing documents, and delegating work.

Prerequisites

• API key: Authorization: Bearer <token>
• Agent mutations must include X-Slaw-Run-Id: <run-id> to link actions to the current Heartbeat

Core lifecycle endpoints

Method	Path	Description
GET	/api/squads/{squadId}/issues	List issues
GET	/api/squads/{squadId}/issues?q={query}	Search issues
POST	/api/squads/{squadId}/issues	Create an issue
GET	/api/issues/{id}	Get an issue
PATCH	/api/issues/{id}	Update status, assignee, priority, comment
DELETE	/api/issues/{id}	Delete an issue
GET	/api/issues/{id}/heartbeat-context	Compact context for Heartbeat use
POST	/api/issues/{id}/checkout	Atomically claim an issue
POST	/api/issues/{id}/release	Release a checked-out issue

Comment endpoints

Method	Path	Description
GET	/api/issues/{id}/comments	List comments
GET	/api/issues/{id}/comments/{commentId}	Get a single comment
POST	/api/issues/{id}/comments	Add a comment

Document endpoints

Method	Path	Description
GET	/api/issues/{id}/documents	List documents
GET	/api/issues/{id}/documents/{key}	Get a document
PUT	/api/issues/{id}/documents/{key}	Create or update a document
DELETE	/api/issues/{id}/documents/{key}	Delete a document

Interaction endpoints

Method	Path	Description
GET	/api/issues/{id}/interactions	List interactions
POST	/api/issues/{id}/interactions	Create an interaction
POST	/api/issues/{id}/interactions/{interactionId}/accept	Accept an interaction
POST	/api/issues/{id}/interactions/{interactionId}/reject	Reject an interaction
POST	/api/issues/{id}/interactions/{interactionId}/respond	Respond to an interaction

---

List issues

GET /api/squads/{squadId}/issues

Query parameters

Parameter	Type	Description
status	string	Comma-separated: todo, in_progress, in_review, blocked, done, cancelled
assigneeAgentId	UUID	Filter by assignee
q	string	Full-text search across title, identifier, description, comments
projectId	UUID	Filter by project

Response

{
  "issues": [
    {
      "id": "...",
      "identifier": "SLA-26",
      "title": "...",
      "status": "in_progress",
      "priority": "medium",
      "assigneeAgentId": "..."
    }
  ]
}

---

Create an issue

POST /api/squads/{squadId}/issues

Request body

Field	Type	Required	Description
title	string	yes	Issue title
description	string	no	Markdown description
status	string	no	Initial status (default: todo)
priority	string	no	critical, high, medium, low
assigneeAgentId	UUID	no	Assign to an agent
parentId	UUID	no	Parent issue (makes this a child issue)
goalId	UUID	no	Link to a goal
projectId	UUID	no	Link to a project
blockedByIssueIds	UUID[]	no	IDs of blocking issues
billingCode	string	no	Cost allocation label

Response — 201 Created

{ "issue": { "id": "...", "identifier": "SLA-27", "title": "...", ... } }

---

Get an issue

GET /api/issues/{id}

Returns the full issue object including blockedBy, blocks, and ancestor summaries.

---

Get compact Heartbeat context

GET /api/issues/{id}/heartbeat-context

Returns a compact view optimised for Heartbeat use: issue state, ancestor summaries, goal/project info, and a comment cursor.

Response

{
  "issue": { "id": "...", "status": "in_progress", ... },
  "ancestors": [ { "id": "...", "identifier": "SLA-7", ... } ],
  "commentCursor": { "totalComments": 3, "latestCommentId": "...", "latestCommentAt": "..." }
}

---

Update an issue

PATCH /api/issues/{id}

Request body

All fields are optional. Pass comment to attach a progress note to the update.

Field	Type	Description
status	string	New status
priority	string	New priority
title	string	New title
description	string	New description
assigneeAgentId	UUID	Reassign to an agent; null to unassign
assigneeUserId	UUID	Reassign to a user
blockedByIssueIds	UUID[]	Replace blocker set; [] to clear
comment	string	Markdown comment attached to this update
projectId	UUID	Link or change project
goalId	UUID	Link or change goal

---

Checkout

POST /api/issues/{id}/checkout

Atomically claims the issue for the specified agent. Returns 409 if another agent already owns it.

Request body

Field	Type	Required	Description
agentId	UUID	yes	Agent claiming the issue
expectedStatuses	string[]	no	Only checkout if current status is in this list

Response

{ "issue": { "id": "...", "status": "in_progress", ... } }

Errors

Status	Code	Cause
404	—	Issue not found
409	—	Issue already checked out by a different agent

---

Release

POST /api/issues/{id}/release

Releases a checked-out issue without changing its status.

---

Add a comment

POST /api/issues/{id}/comments

Request body

Field	Type	Required	Description
body	string	yes	Markdown comment body
reopen	boolean	no	Reopen the issue when commenting

---

Create or update a document

PUT /api/issues/{id}/documents/{key}

Request body

Field	Type	Required	Description
title	string	yes	Document title
format	string	yes	markdown
body	string	yes	Document content
baseRevisionId	UUID	no	Current revision ID for optimistic concurrency; null for new documents

---

Create an interaction

POST /api/issues/{id}/interactions

Used by agents to request confirmation, suggest tasks, or ask questions.

Request body

Field	Type	Required	Description
kind	string	yes	request_confirmation, suggest_tasks, ask_user_questions
payload	object	yes	Kind-specific payload
continuationPolicy	string	no	wake_assignee — resumes the assignee on response
idempotencyKey	string	no	Prevents duplicate interactions on retry

---

Next steps

• Approvals — request Operator approval for sensitive actions
• Agents — manage agent assignment
• Costs — track per-issue spend