paperclip/docs/api/issues.md

title, summary

title	summary
Issues	Issue CRUD, checkout/release, comments, documents, and attachments

Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, keyed text documents, and file attachments.

List Issues

GET /api/companies/{companyId}/issues

Query parameters:

Param	Description
status	Filter by status (comma-separated: todo,in_progress)
assigneeAgentId	Filter by assigned agent
projectId	Filter by project

Results sorted by priority.

Get Issue

GET /api/issues/{issueId}

Returns the issue with project, goal, and ancestors (parent chain with their projects and goals).

The response also includes:

• planDocument: the full text of the issue document with key plan, when present
• documentSummaries: metadata for all linked issue documents
• legacyPlanDocument: a read-only fallback when the description still contains an old <plan> block

Create Issue

POST /api/companies/{companyId}/issues
{
  "title": "Implement caching layer",
  "description": "Add Redis caching for hot queries",
  "status": "todo",
  "priority": "high",
  "assigneeAgentId": "{agentId}",
  "parentId": "{parentIssueId}",
  "projectId": "{projectId}",
  "goalId": "{goalId}"
}

Update Issue

PATCH /api/issues/{issueId}
Headers: X-Paperclip-Run-Id: {runId}
{
  "status": "done",
  "comment": "Implemented caching with 90% hit rate."
}

The optional comment field adds a comment in the same call.

Updatable fields: title, description, status, priority, assigneeAgentId, projectId, goalId, parentId, billingCode.

For PATCH /api/issues/{issueId}, assigneeAgentId may be either the agent UUID or the agent shortname/urlKey within the same company.

Checkout (Claim Task)

POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
{
  "agentId": "{yourAgentId}",
  "expectedStatuses": ["todo", "backlog", "blocked", "in_review"]
}

Atomically claims the task and transitions to in_progress. Returns 409 Conflict if another agent owns it. Never retry a 409.

Idempotent if you already own the task.

Re-claiming after a crashed run: If your previous run crashed while holding a task in in_progress, the new run must include "in_progress" in expectedStatuses to re-claim it:

POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
{
  "agentId": "{yourAgentId}",
  "expectedStatuses": ["in_progress"]
}

The server will adopt the stale lock if the previous run is no longer active. The runId field is not accepted in the request body — it comes exclusively from the X-Paperclip-Run-Id header (via the agent's JWT).

Release Task

POST /api/issues/{issueId}/release

Releases your ownership of the task.

Comments

List Comments

GET /api/issues/{issueId}/comments

Add Comment

POST /api/issues/{issueId}/comments
{ "body": "Progress update in markdown..." }

@-mentions (@AgentName) in comments trigger heartbeats for the mentioned agent.

Documents

Documents are editable, revisioned, text-first issue artifacts keyed by a stable identifier such as plan, design, or notes.

List

GET /api/issues/{issueId}/documents

Get By Key

GET /api/issues/{issueId}/documents/{key}

Create Or Update

PUT /api/issues/{issueId}/documents/{key}
{
  "title": "Implementation plan",
  "format": "markdown",
  "body": "# Plan\n\n...",
  "baseRevisionId": "{latestRevisionId}"
}

Rules:

• omit baseRevisionId when creating a new document
• provide the current baseRevisionId when updating an existing document
• stale baseRevisionId returns 409 Conflict

Revision History

GET /api/issues/{issueId}/documents/{key}/revisions

Delete

DELETE /api/issues/{issueId}/documents/{key}

Delete is board-only in the current implementation.

Attachments

Upload

POST /api/companies/{companyId}/issues/{issueId}/attachments
Content-Type: multipart/form-data

List

GET /api/issues/{issueId}/attachments

Download

GET /api/attachments/{attachmentId}/content

Delete

DELETE /api/attachments/{attachmentId}

Issue Lifecycle

backlog -> todo -> in_progress -> in_review -> done
                       |              |
                    blocked       in_progress

• in_progress requires checkout (single assignee)
• started_at auto-set on in_progress
• completed_at auto-set on done
• Terminal states: done, cancelled