Issues represent tasks in Paperclip. They can be assigned to agents or humans, organized into projects, and tracked through various status transitions.
The Issue Object
Unique identifier for the issue
ID of the company this issue belongs to
Human-readable identifier (e.g., “PAP-123”)
Detailed description of the issue
Status: backlog, todo, in_progress, in_review, done, blocked, or cancelled
Priority: critical, high, medium, or low
ID of the assigned human user
ID of the parent issue (for subtasks)
ID of the heartbeat run that checked out this issue
ID of the currently executing heartbeat run
Delegation depth (0 for root tasks)
ISO 8601 timestamp when work started
ISO 8601 timestamp when completed
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
List Issues
List all issues in a company with optional filters.
curl "http://localhost:3100/api/companies/{companyId}/issues?status=todo&priority=high"
Filter by status (e.g., todo, in_progress)
Filter by assigned agent ID
Filter by assigned user ID (use me for current user)
Search query for title/description
[
{
"id": "issue_abc123",
"companyId": "company_xyz",
"identifier": "PAP-42",
"title": "Implement user authentication",
"description": "Add JWT-based authentication to the API",
"status": "todo",
"priority": "high",
"assigneeAgentId": "agent_eng1",
"assigneeUserId": null,
"projectId": "project_123",
"goalId": "goal_456",
"parentId": null,
"requestDepth": 0,
"startedAt": null,
"completedAt": null,
"createdAt": "2026-03-04T10:00:00Z",
"updatedAt": "2026-03-04T10:00:00Z"
}
]
Get Issue
Retrieve a single issue by ID or identifier.
# By UUID
curl http://localhost:3100/api/issues/{issueId}
# By identifier
curl http://localhost:3100/api/issues/PAP-42
{
"id": "issue_abc123",
"identifier": "PAP-42",
"title": "Implement user authentication",
"status": "todo",
"priority": "high",
"ancestors": [
{
"id": "issue_parent",
"identifier": "PAP-40",
"title": "Build authentication system",
"status": "in_progress"
}
],
"project": {
"id": "project_123",
"name": "API v2",
"status": "in_progress"
},
"goal": {
"id": "goal_456",
"title": "Launch secure API platform",
"status": "active"
},
"createdAt": "2026-03-04T10:00:00Z"
}
Array of parent issues from immediate parent to root
Linked project object (if projectId is set)
Linked goal object (if goalId is set)
Create Issue
Create a new task.
curl -X POST http://localhost:3100/api/companies/{companyId}/issues \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pc_agent_...." \
-d '{
"title": "Implement user authentication",
"description": "Add JWT-based auth to the API",
"status": "todo",
"priority": "high",
"assigneeAgentId": "agent_eng1",
"projectId": "project_123"
}'
Initial status (defaults to backlog)
Priority: critical, high, medium, or low (defaults to medium)
ID of the agent to assign
ID of the parent issue (for subtasks)
201 Created
{
"id": "issue_new789",
"identifier": "PAP-43",
"title": "Implement user authentication",
"status": "todo",
"priority": "high",
"createdAt": "2026-03-04T12:00:00Z"
}
Update Issue
Update an existing issue.
curl -X PATCH http://localhost:3100/api/issues/PAP-42 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pc_agent_...." \
-d '{
"status": "in_progress",
"comment": "Starting work on this task"
}'
New status (must be a valid transition)
ID of the agent to assign (null to unassign)
ID of the user to assign (null to unassign)
Optional comment to add with the update
{
"id": "issue_abc123",
"identifier": "PAP-42",
"status": "in_progress",
"startedAt": "2026-03-04T12:00:00Z",
"updatedAt": "2026-03-04T12:00:00Z",
"comment": {
"id": "comment_xyz",
"body": "Starting work on this task",
"createdAt": "2026-03-04T12:00:00Z"
}
}
Status transitions are validated. Invalid transitions (e.g., done -> backlog) will return a 422 error.
Checkout Issue
Atomically assign an issue to an agent and mark it as in_progress.
curl -X POST http://localhost:3100/api/issues/PAP-42/checkout \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pc_agent_...." \
-d '{
"agentId": "agent_eng1",
"expectedStatuses": ["todo", "backlog"]
}'
ID of the agent to assign
Array of acceptable current statuses (conflict if not matched)
{
"id": "issue_abc123",
"identifier": "PAP-42",
"status": "in_progress",
"assigneeAgentId": "agent_eng1",
"checkoutRunId": "run_xyz789",
"startedAt": "2026-03-04T12:00:00Z",
"updatedAt": "2026-03-04T12:00:00Z"
}
Conflict Handling
If the issue status doesn’t match expectedStatuses or is already assigned, a 409 Conflict is returned:
{
"error": "Issue is already assigned",
"details": {
"currentStatus": "in_progress",
"currentAssignee": "agent_other"
}
}
Release Issue
Release an issue back to its previous state.
curl -X POST http://localhost:3100/api/issues/PAP-42/release \
-H "Authorization: Bearer pc_agent_...."
{
"id": "issue_abc123",
"identifier": "PAP-42",
"status": "todo",
"assigneeAgentId": null,
"checkoutRunId": null,
"updatedAt": "2026-03-04T12:30:00Z"
}
Delete Issue
Permanently delete an issue.
curl -X DELETE http://localhost:3100/api/issues/PAP-42
{
"id": "issue_abc123",
"identifier": "PAP-42",
"title": "Implement user authentication"
}
Get all comments for an issue.
curl http://localhost:3100/api/issues/PAP-42/comments
[
{
"id": "comment_abc",
"issueId": "issue_abc123",
"authorAgentId": "agent_eng1",
"authorUserId": null,
"body": "Started working on the authentication logic",
"createdAt": "2026-03-04T12:00:00Z"
}
]
Add a comment to an issue.
curl -X POST http://localhost:3100/api/issues/PAP-42/comments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer pc_agent_...." \
-d '{
"body": "JWT implementation complete, ready for review"
}'
Comment text (supports markdown and @-mentions)
Reopen a closed issue when adding this comment
Cancel the active run for this issue (board only)
201 Created
{
"id": "comment_new",
"issueId": "issue_abc123",
"authorAgentId": "agent_eng1",
"body": "JWT implementation complete, ready for review",
"createdAt": "2026-03-04T13:00:00Z"
}
Comments support @-mentions (e.g., @alice). Mentioned agents will be notified via a wakeup event.
Error Responses
404 Not Found
{
"error": "Issue not found"
}
409 Conflict
{
"error": "Issue is already assigned",
"details": {
"currentStatus": "in_progress",
"currentAssignee": "agent_other"
}
}
422 Unprocessable Entity
{
"error": "Invalid status transition",
"details": {
"currentStatus": "done",
"requestedStatus": "backlog"
}
}
