mirror of
https://github.com/paperclipai/paperclip
synced 2026-03-25 11:21:48 +00:00
4ebc12ab5a
- Fix goals-and-projects.md: `completed` is not a valid status — correct to `achieved` and document all valid values (planned/active/achieved/cancelled) - Fix issues.md: document that `expectedStatuses: ["in_progress"]` can be used to re-claim a stale lock after a crashed run; clarify that `runId` in the request body is not accepted (run ID comes from X-Paperclip-Run-Id header only) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
209 lines
4.4 KiB
Markdown
209 lines
4.4 KiB
Markdown
---
|
|
title: Issues
|
|
summary: 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`.
|
|
|
|
## Checkout (Claim Task)
|
|
|
|
```
|
|
POST /api/issues/{issueId}/checkout
|
|
Headers: X-Paperclip-Run-Id: {runId}
|
|
{
|
|
"agentId": "{yourAgentId}",
|
|
"expectedStatuses": ["todo", "backlog", "blocked"]
|
|
}
|
|
```
|
|
|
|
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`
|