paperclip-docs/docs/reference/api/cases.md

paperclip_version, seo_title, seo_description

paperclip_version	seo_title	seo_description
v2026.1106.0	Cases API	Cases handle document-heavy work that will not fit one issue — research write-ups, investigations, proposals, legal and compliance material.

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.

A case can also carry a primary task that moves between agents phase by phase. Instead of opening a new task for each step, an agent hands the same task to the next agent with a case handoff. For a walkthrough of how this looks in the app, see the Cases guide.

Cases are company-scoped, and — like the rest of the control-plane API — company access is enforced on every request. On top of that, a case stays inside the permissions of the tasks and projects it came from: if a case was started from a private task, callers who can't read that task can't read the case either, and unlinking the task doesn't lift the restriction. 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:

Field	Meaning
caseType	A free-form string you choose, 1–120 characters — for example investigation, proposal, or legal_review. Cases are grouped and filtered by type.
key	Optional stable key within a caseType. The pair (caseType, key) is unique per company and drives the upsert behavior on create (see below).
title	Required, 1–500 characters.
summary	Optional free text, up to 8,000 characters.
status	One of draft, in_progress, in_review, approved, done, cancelled. Defaults to draft.
fields	An arbitrary JSON object for your own structured data. Defaults to {}.
projectId	Optional project the case belongs to. Must belong to the same company.
parentCaseId	Optional parent case, so cases can nest. Must belong to the same company, and a case cannot be its own parent.
completedAt	Set by the server when the status becomes done or cancelled, and cleared otherwise.
workIssueId	The case's primary task, if it has one. Every handoff reuses this same task. Set by the handoff routes, not by create or update.
workflowId	The reusable workflow the case currently follows, or null when it runs on its own case instructions. Set by the handoff routes.
phase	The current phase name, as set by the last applied handoff (for example triage or verification). A free-form label — Paperclip doesn't enforce phase order.
handoffVersion	A counter that increases each time a handoff is accepted. Send it back as expectedHandoffVersion so a handoff fails cleanly if someone else routed the case first.

Status values

Status	Typical meaning	Terminal?
draft	Just created, still being shaped.	No
in_progress	Actively being worked.	No
in_review	Paused for review or sign-off.	No
approved	Reviewed and accepted, not yet closed out.	No
done	Complete. Sets completedAt.	Yes
cancelled	Abandoned. Sets completedAt.	Yes

---

List Cases

GET /api/companies/{companyId}/cases

Return the company's cases, newest activity first.

Query Parameters

Param	Description
type / types	Filter by one case type, or several. types accepts a comma-separated list or repeated params.
status / statuses	Filter by one status or a list. The special value status=active returns everything that is not done or cancelled.
project / projectId / projectIds	Filter by one or more projects.
includeNoProject	When true (or 1), also include cases with no project. Combine with projectIds to union both sets.
label / labelId	Filter to cases carrying a given label.
parent	Filter to the direct children of a given parent case (UUID).
q	Case-insensitive search across identifier, title, summary, and key.
includeAncestors	When true, also return the parent chain of every matched case. Each returned row carries matchesListFilters — true for rows that matched your filters, false for ancestors pulled in only for context.
sortField	updated (default), created, title, status, or type.
sortDir	asc or desc (default).
groupBy	none (default), status, type, or project. Rows come back ordered by the group first, then by your sort.
limit	Positive integer, 1–200. Defaults to 100.
offset	Skip this many matching cases, for paging. 0–100,000. Defaults to 0.

Each row also carries two work summaries:

• workIssue — a compact view of the primary task (id, identifier, title, status, statusVersion, assigneeAgentId, assigneeAgentName), or null if there's no primary task or you can't read it.
• pendingHandoff — the handoff currently in flight for that task (with fromAgentName and toAgentName), or null.

---

List Case Types

GET /api/companies/{companyId}/cases/types

Return a sorted array of the distinct caseType values across the cases you can see — handy for building a type filter. Types used only by cases you can't read are left out.

---

Get Case

GET /api/cases/{id}

Return the full case detail. Query parameters:

• includeDocumentBodies — defaults to true. Set false to return document metadata without the document bodies.

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.
• workIssue and pendingHandoff — the same work summaries returned by the list route.
• workflow — { id, name } of the reusable workflow in workflowId, or null.
• taskDocuments — references to the documents on the primary task and on linked tasks. Each entry has an id, taskId, taskIdentifier, key, scope (primary or linked), the document metadata (no body), and a readPath such as /api/issues/{taskId}/documents/{key} for fetching the body. The primary task's workflow document comes first. Only tasks you can read are included.
• taskDocumentsOmitted — true when there were more task documents than the response includes.

Issue links, the parent case, and task documents are filtered to what you're allowed to read.

---

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:

Field	Required	Notes
caseType	yes	1–120 characters.
title	yes	1–500 characters.
key	no	Stable key within the type; null is allowed.
summary	no	Up to 8,000 characters, or null.
status	no	Defaults to draft on create.
fields	no	Arbitrary JSON object.
projectId	no	Must belong to the company, or null.
parentCaseId	no	Must belong to the company, or null.

Unknown fields are rejected. This route doesn't start a workflow or set a primary task — use Start a handoff for that. 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" }).
• phase, workIssueId, and assignment aren't editable here — they change only through case handoffs.
• When an agent run writes to a case, the run must still own its task. A Paperclip Runner run whose task has moved on (for example, after it handed the task off) gets 403 Forbidden with { "error": "The task is no longer writable by this run" }. The same applies to document, annotation, and attachment writes.
• 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:

Role	Meaning
origin	The issue this case originated from.
work	An issue doing the work for this case.
reference	A related issue, linked for context.

Link an Issue

POST /api/cases/{id}/links

Request body:

Field	Required	Notes
issueId	yes	UUID of an issue in the same company.
role	yes	One of origin, work, reference.

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

New work belongs on tasks. For cases with a primary task, drafts, briefs, and reports live as ordinary task documents, and case detail surfaces them through taskDocuments. The routes below remain for documents saved directly on a case.

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:

Field	Required	Notes
body	yes	Document content, up to 200,000 characters.
title	no	Optional document title.
format	no	Defaults to markdown.
changeSummary	no	Optional note attached to the new revision, up to 1,000 characters.
baseRevisionId	no on create, required on update	The revision you based your edit on.

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 deployment-level attachment size limit (PAPERCLIP_ATTACHMENT_MAX_BYTES) are rejected with 422 Unprocessable Entity ({ "error": "Attachment exceeds {n} bytes" }). The default limit is 10 MiB. This cap is set per instance, not per company.

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:

Kind	Emitted when
created	A case is created.
updated	A case is updated with no more specific change.
status_changed	The case status changes.
fields_changed	The fields object is updated.
child_linked	The case is re-parented under another case.
issue_linked	An issue is linked (manually or auto-linked).
issue_unlinked	An issue link is removed.
document_revised	A case document gains a new revision (including restores).
attachment_added	A file is uploaded.
label_added	A label is attached.
label_removed	A label is removed.
handoff_requested	A handoff is accepted and waiting to be applied.
handoff_applied	The primary task is reassigned to the next agent.
handoff_delivered	The next agent's wake-up is queued.
handoff_completed	A handoff to done settles because the primary task was completed.
handoff_cancelled	A pending handoff is cancelled.

---

Case handoffs

A handoff passes a case's primary task from one agent to the next — or to done to close the case. The task stays the same; only its assignee, the case phase (and workflowId, if the handoff adopts a workflow), and the handoffVersion change. Agents on the Paperclip Runner use the native create_case, read_case, update_case, and handoff_case tools, which go through the same rules as these routes. (For reusable workflow definitions, see Workflows.)

Handoffs are durable. Paperclip records the intent first, waits until the outgoing agent's run has stopped and its workspace has settled, then reassigns the task and queues the next agent's wake-up. A restart in the middle picks the handoff up again rather than losing or duplicating it. Only one handoff can be pending per case at a time.

On the routes below, {caseId} must be the case UUID — the human-readable identifier isn't accepted here.

Start a handoff

POST /api/companies/{companyId}/case-handoffs

There are two shapes. An agent handoff sends the primary task to an agent:

Field	Required	Notes
idempotencyKey	yes	1–240 characters. Retrying with the same key and the same body returns the original receipt; a different body under the same key is a 409.
case	yes	Either { "id": "<case-uuid>" } for an existing case, or { "create": { ... } } to create one. create accepts caseType, title, and optional summary, fields, and projectId.
toAgentId	yes	The agent receiving the task.
phase	yes	1–120 characters, such as triage or implementation.
instructions	yes	What the next agent should do, up to 20,000 characters.
workflow_document_text	when creating the primary task, unless workflowId is set	The workflow description, saved verbatim as the task's workflow document (titled Workflow). Up to 200,000 characters and not blank. Not accepted on later handoffs, and can't be combined with workflowId.
workflowId	no	A reusable workflow to adopt, or null to detach. Can stand in for workflow_document_text when creating the primary task. See Adopting a workflow.
expectedHandoffVersion	for an existing case	The case's current handoffVersion.
expectedIssueStatusVersion	when the task already exists: a case with a primary task, or bindIssueId	That task's current status version. A missing value returns 422.
bindIssueId	no	Use an existing task as the primary task instead of creating one. Only for a case that has no primary task yet.
initialDocuments	no	Up to 20 { key, title, body } documents seeded on a newly created primary task. The key workflow is reserved, keys must be unique, and all bodies together (including the workflow text or an adopted workflow's prompt) are capped at 200,000 characters.

Adopting a workflow

workflowId tells Paperclip what to do with the case's reusable workflow on this handoff:

Value	Effect
omitted	Keep the current workflow and leave the task's workflow document alone.
a workflow ID	Adopt that workflow's latest prompt into the task's workflow document. Send the case's current workflowId to refresh it.
null	Detach. The case's workflowId becomes null; the workflow document is kept as it is.

The prompt is captured when the handoff is accepted, together with the workflow document's current revision — later edits to the shared definition don't affect this handoff. The new workflow, the new phase, and the document revision are applied together when the handoff is applied, after the outgoing run settles. If the workflow document changed after acceptance, Paperclip doesn't overwrite it: the handoff moves to cancelled with lastError set to Document was updated by someone else, and the task, phase, and workflow stay as they were. Reload the case and hand off again.

A done handoff asks Paperclip to close the case when its primary task completes:

Field	Required	Notes
to	yes	The literal "done".
idempotencyKey	yes	As above.
case	yes	{ "id": "<case-uuid>" }. The case must already have a primary task.
instructions	yes	Up to 20,000 characters.
expectedHandoffVersion	yes	The case's current handoffVersion.
expectedIssueStatusVersion	yes	The primary task's current status version.

A done handoff doesn't move the task or satisfy any completion gate. It waits in awaiting_completion until the task is completed normally, including any required review or approval, then closes the case and sets its phase to done. Stopping the run, cancelling the task, or reassigning it cancels a waiting done handoff.

A new handoff responds 202 Accepted; a replay of an earlier one responds 200 OK. The receipt contains:

Field	Meaning
handoffId, caseId, taskId, taskIdentifier	What was handed off.
handoffVersion	The case's routing version for this handoff.
destinationKind	agent or done.
state	See handoff states.
completedAt	When a done handoff settled, otherwise null.
callerMustYield	true when the calling agent run handed off its own task and must end its turn now.
replayed	true when this is the receipt of an earlier identical request.

Common errors: 409 when the case or task changed since you read it (reload and retry), when a handoff is already pending for the case, or when the task is already another case's primary task; 422 when the task isn't an ordinary work task, has unresolved blockers or review, or would break a private task or project boundary; 403 when the recipient can't access the case.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/companies/{companyId}/case-handoffs" \
  -d '{
    "idempotencyKey": "csv-export-verify-1",
    "case": { "id": "{caseId}" },
    "toAgentId": "{verifierAgentId}",
    "phase": "verification",
    "instructions": "The export is implemented and the checks pass. Verify it against the brief.",
    "expectedHandoffVersion": 2,
    "expectedIssueStatusVersion": 5
  }'

Handoff states

State	Meaning
awaiting_release	Accepted. Waiting for the outgoing agent's run and workspace to settle.
pending_dispatch	The task has been reassigned; the next agent's wake-up is being queued.
delivered	The wake-up was queued. This doesn't prove the next agent has run yet.
awaiting_completion	A done handoff waiting for the primary task to complete.
completed	The done handoff settled and the case closed.
cancelled	The handoff was cancelled. An already-applied reassignment is not reversed.

List handoffs

GET /api/cases/{caseId}/handoffs

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

• limit — 1–100. Defaults to 25.
• cursor — the nextCursor from a previous page.
• before — an ISO timestamp; return only handoffs created before it.

The response is { items, nextCursor, canControl }. Each item includes the handoff's phase, instructions, state, destinationKind, workflowTransition, fromAgentId / toAgentId with fromAgentName / toAgentName, version, timestamps, and any lastError. canControl is true when you're allowed to retry or cancel the pending handoff.

workflowTransition records which workflow and phase the handoff moved between: { from: { workflowId, name, phase }, to: { workflowId, name, phase }, documentRevisionId }. A null workflowId and name mean the case's own instructions rather than a reusable workflow. The names are captured at the time, so they stay put if a definition is renamed later. The captured prompt itself is never returned. The same workflowTransition also appears in the handoff_* events and their Audit entries.

Retry or cancel a pending handoff

POST /api/cases/{caseId}/handoffs/{handoffId}/retry
POST /api/cases/{caseId}/handoffs/{handoffId}/cancel

Both require control of the primary task. Retry schedules another delivery attempt for a pending agent handoff right away; on a done handoff or a handoff that's no longer pending it simply returns the current record. Cancel cancels a pending handoff — it never reverses a reassignment that already happened — and still works while Cases is turned off. Both return the handoff record.

---

Workflows

A workflow is a reusable, company-shared set of case instructions: just a name and a Markdown prompt. Instead of writing workflow_document_text for every case, you save a workflow once and pass its ID as workflowId on a handoff. Each case keeps its own copy in its primary task's workflow document, so editing a definition only reaches a case when a handoff adopts or refreshes it.

Like the rest of this page, these routes return 403 with { "error": "Cases are disabled" } until enableCases is on. There's no UI for workflows yet, and no delete route.

Agents on the Paperclip Runner manage workflows with four optional Cases tools: list_workflows, read_workflow, create_workflow, and update_workflow. They call the routes below.

List Workflows

GET /api/companies/{companyId}/workflows

Return the company's workflows, sorted by name, as an array of { id, companyId, name, createdAt, updatedAt } — prompts aren't included. Query parameters:

• limit — 1–100. Defaults to 50.
• offset — 0–100,000. Defaults to 0.

Get a Workflow

GET /api/workflows/{id}

Return the full workflow, including its prompt, createdByAgentId, and createdByUserId. The response carries an ETag holding a fingerprint of the workflow. Pass that fingerprint (without the quotes) as the snapshot query parameter on later reads to make sure you're still reading the same version: if the workflow has changed since, the request fails with 409 Conflict. A workflow in another company — or one that doesn't exist — returns 404 with { "error": "Workflow not found" }.

Create a Workflow

POST /api/companies/{companyId}/workflows

Field	Required	Notes
name	yes	1–200 characters, trimmed.
prompt	yes	The workflow Markdown, up to 200,000 characters and not blank.

Unknown fields are rejected. Creating or editing a workflow needs the same permission as creating a case. Responds 201 Created with the workflow's metadata (everything except prompt).

Update a Workflow

PATCH /api/workflows/{id}

Send name, prompt, or both, with the same limits as create. Returns the updated metadata. Cases already using the workflow keep their copy until a handoff refreshes it.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/companies/{companyId}/workflows" \
  -d '{
    "name": "Bug fix",
    "prompt": "Triage the report, implement the fix, then hand off for verification with the evidence saved."
  }'

---

Where to go next

• Cases guide — how case workflows, handoffs, and the read-only Cases pages look in the app.
• 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.