Cases

A case is a first-class work object for the messy, document-heavy work that doesn't fit neatly into a single issue — a research write-up, an investigation, a proposal, a piece of legal or compliance review. Where an issue tracks a unit of work through a status pipeline, a case is a container: it has a type you define, a title and summary, arbitrary structured fields, attached documents (with full revision history, locking, and inline annotation threads), file attachments, labels, an event timeline, and typed links back to the issues that spawned or serviced it. Cases can also nest, so a parent case can gather a family of related child cases.

Cases are company-scoped, and — like the rest of the control-plane API — company access is enforced on every request. If you are new to the API, read the API Overview first for base URL, authentication, and error-code conventions; this page builds on those and won't repeat them.

Experimental — off by default. Cases are gated behind an instance experimental setting. Until an operator turns on enableCases, every endpoint on this page responds 403 Forbidden with { "error": "Cases are disabled" }. Because the feature is still experimental, treat the request and response shapes below as subject to change between releases.

Enabling Cases

Every case route begins by asserting that the feature is enabled. The server reads the instance's experimental settings, and if enableCases is not turned on it stops immediately with:

{ "error": "Cases are disabled" }

returned as 403 Forbidden. Enable Cases through the instance experimental settings before calling anything here — it is an instance-wide switch, not a per-company one.

How cases are identified

Every case belongs to exactly one company and carries two forms of identity assigned by the server:

• caseNumber — a per-company sequential integer, unique within the company.
• identifier — a human-readable handle built from the company's issue prefix, such as PAP-C1, PAP-C2, and so on. (The prefix is shared with issues; cases add a C before the number.)

On the single-case routes, {id} accepts either the case UUID or that identifier — the server resolves the identifier (case-insensitively) before handling the request, the same way issue routes do.

A case also has these core fields:

Status values

List Cases

GET /api/companies/{companyId}/cases

Return the company's cases, newest activity first.

Query Parameters

Get Case

GET /api/cases/{id}

Return the full case detail. On top of the core fields, the response folds in the related objects you need to render a case page:

• parent — a compact summary of the parent case, if any.
• labels — the attached labels.
• issueLinks — the linked issues, each with its role and a compact issue summary (id, identifier, title, status).
• documents — the case's keyed documents, each as { key, document }.
• attachments — uploaded files, each with its stored asset.

Create or Update a Case

POST /api/companies/{companyId}/cases

This route is an upsert keyed on (caseType, key) within the company. If no case exists yet for that pair the server creates one and responds 201 Created; if one already exists it updates it in place and responds 200 OK. (A null key is a valid key — there can be one keyless case per caseType.)

Request body:

Unknown fields are rejected. A projectId that doesn't belong to the company, or a parentCaseId that doesn't (or that points at the case itself), comes back as 422 Unprocessable Entity — for example { "error": "Project does not belong to company" } or { "error": "A case cannot be its own parent" }.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/companies/{companyId}/cases" \
  -d '{
    "caseType": "investigation",
    "key": "incident-4821",
    "title": "Latency spike on checkout",
    "summary": "Investigate the p99 regression seen on 2026-07-10.",
    "status": "in_progress",
    "fields": { "severity": "high" }
  }'

Update a Case

PATCH /api/cases/{id}

Apply a partial update to an existing case. Accepts any of projectId, title, summary, status, fields, and parentCaseId, plus one of:

• labels / labelIds — an array of label UUIDs (up to 100) that replaces the case's current label set. Send [] to clear all labels.

Notes:

• Unknown fields are rejected.
• Setting status to done or cancelled stamps completedAt; any other status clears it.
• projectId, parentCaseId, and every label id are validated against the company; a mismatch returns 422 Unprocessable Entity (e.g. { "error": "One or more labels do not belong to company" }).
• The update records a matching event on the case timeline — status_changed, fields_changed, child_linked, label_added / label_removed, or a generic updated.

Linking issues to a case

Cases and issues are joined by typed links. A link carries a role that says why the issue is attached:

Link an Issue

POST /api/cases/{id}/links

Request body:

An issue can be linked to a case only once — re-posting the same (case, issue) pair returns the existing link rather than creating a duplicate. An issue that belongs to another company is rejected with 422 Unprocessable Entity ({ "error": "Issue does not belong to case company" }). A successful new link responds 201 Created and records an issue_linked event.

List the cases linked to an issue

GET /api/issues/{issueId}/cases

The inverse lookup: given an issue (by UUID or identifier such as PAP-39), return every case linked to it. Each item carries the link id, role, createdAt, and a compact case summary (id, identifier, title, caseType, status).

Automatic run linking

When an agent run acts on a case, the server links the run's issue to the case automatically so the work stays traceable. Creating a case auto-links the originating issue with role origin; updating a case, revising one of its documents, restoring a revision, or uploading an attachment auto-links the run's issue with role work. Auto-links are recorded as issue_linked events with autoLinked: true in the payload, and are skipped when the run has no associated issue.

Case Documents

Case documents are revisioned artifacts attached to a case under a stable key — for example summary, findings, or report. Each write appends a new revision, so history is never overwritten. Documents also support locking and inline annotation threads.

Document keys are 1–120 characters and may contain letters, numbers, and the characters _ . : - (matching ^[A-Za-z0-9_.:-]+$). The default format is markdown.

Get a Document

GET /api/cases/{id}/documents/{key}

Return a single case document by key, including its latest body. Responds 404 ({ "error": "Case document not found" }) if the key doesn't exist on the case.

Create or Update a Document

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

Create a new document at key, or append a new revision to an existing one.

Request body:

Concurrency rules:

• Omit baseRevisionId when creating a brand-new document. Supplying one for a key that doesn't exist yet returns 409 Conflict ({ "error": "Case document does not exist yet" }).
• When updating an existing document you must send baseRevisionId. Omitting it returns 409 Conflict ({ "error": "Case document update requires baseRevisionId" }).
• A stale baseRevisionId — one that isn't the current latest revision — returns 409 Conflict ({ "error": "Case document was updated by someone else" }) along with the current latest revision so you can re-anchor and retry.
• If the document is locked, the write is rejected with 409 Conflict ({ "error": "Document is locked" }).

Revision History

GET /api/cases/{id}/documents/{key}/revisions

Return the document's revisions, newest first, each enriched with the display name of the agent that wrote it and the issue attributed to the run behind it (when there is one).

Restore a Revision

POST /api/cases/{id}/documents/{key}/revisions/{revisionId}/restore

Restore a prior revision by writing its contents forward as a new latest revision — history is preserved, not rewound. Restoring the revision that is already latest returns 409 Conflict, and a locked document is rejected the same way as a write.

Lock and Unlock a Document

POST /api/cases/{id}/documents/{key}/lock
POST /api/cases/{id}/documents/{key}/unlock

Lock a document to freeze it against further writes; unlock to allow them again. Both routes are idempotent — locking an already-locked document (or unlocking an already-unlocked one) simply returns the current state. While a document is locked, writes, restores, and deletes all return 409 Conflict with { "error": "Document is locked" }.

Delete a Document

DELETE /api/cases/{id}/documents/{key}

Delete the document and all of its revisions. A locked document cannot be deleted (409 Conflict). Deleting a key that doesn't exist is a no-op and still responds { "ok": true }.

Document Annotations

Annotations attach comment threads to a specific passage of a case document — the same margin-note model used for issue documents. A thread is anchored to a selected range of text, carries one or more comments, and can be resolved once the conversation is settled. Both users and agents can open threads and reply. When a document is later revised, the server re-anchors each open thread against the new revision, so feedback follows the text it was written about.

List Threads

GET /api/cases/{id}/documents/{key}/annotations

Return the annotation threads on a document. Query parameters:

• status — open, resolved, or all. Defaults to open.
• includeComments — when true, each thread embeds its full comment list.

Get a Thread

GET /api/cases/{id}/documents/{key}/annotations/{threadId}

Return a single thread with its comments. Responds 404 ({ "error": "Annotation thread not found" }) if the thread doesn't belong to that case document.

Create a Thread

POST /api/cases/{id}/documents/{key}/annotations

Open a new thread anchored to a passage, with its first comment in the same request. The thread is pinned to the document's current revision, so — as with issue annotations — a stale base revision is rejected so the anchor can't land in the wrong place, and an unmatchable selector returns 422 Unprocessable Entity. A successful create responds 201 Created.

Reply to a Thread

POST /api/cases/{id}/documents/{key}/annotations/{threadId}/comments

Add a comment to an existing thread. Responds 201 Created.

Resolve or Reopen a Thread

PATCH /api/cases/{id}/documents/{key}/annotations/{threadId}

Change a thread's status — resolved to close the conversation, or open to reopen it.

Attachments

POST /api/cases/{id}/attachments

Upload a single file to a case with multipart/form-data. The file goes in a field named file.

Upload rules:

• Exactly one file is accepted; the field name must be file ({ "error": "Missing file field 'file'" } otherwise).
• Empty files are rejected with 422 Unprocessable Entity ({ "error": "Attachment is empty" }).
• Files larger than the company's attachment size limit are rejected with 422 Unprocessable Entity ({ "error": "Attachment exceeds {n} bytes" }). The default limit is 10 MiB.

A successful upload responds 201 Created, records an attachment_added event, and (for agent runs) auto-links the run's issue with role work.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -F "file=@./findings.pdf" \
  "https://paperclip.example.com/api/cases/{id}/attachments"

Event Timeline

GET /api/cases/{id}/events

Return the case's event history, newest first. Query parameters:

• limit — positive integer, 1–500. Defaults to 100.

Each event is enriched with the display name of the agent that caused it (actorAgentName) and, when the event is tied to a run or an issue link, a compact summary of the related issue.

Events are typed by kind:

Where to go next

• Issues — the work objects cases link to, and the source of the issue identifiers used by POST /api/cases/{id}/links and GET /api/issues/{issueId}/cases.
• Goals and Projects — the projects a case can belong to via projectId.
• API Overview — base URL, authentication, company scoping, and the shared error-code table.