Status Cards

A status card is a standing question about a company's work, and the living answer to it. You give the card one message in plain language — what to watch, and how the update should read — and Paperclip's Summarizer compiles that into structured company-search queries, then keeps writing a Markdown summary as the matching issues move.

The API mirrors that lifecycle. You create a card and Paperclip queues a compile task; you ask for refreshes and it queues update tasks; the summarizer agent writes the compiled query and the finished summary back through two dedicated endpoints that only it may call.

Status cards are company-scoped, and 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. Status cards are gated behind an instance experimental setting. Until an operator turns on enableStatusCards, every endpoint on this page responds 404 Not Found with { "error": "Status cards are not enabled" }. Because the feature is still experimental, treat the request and response shapes below as subject to change between releases.

For the board itself — creating cards in the UI, reading the tiles, and what the update policy does — see Status Cards in the experimental section.

Enabling status cards

Every route here starts by asking the instance whether status cards are on. The server reads the instance's experimental settings, and if enableStatusCards is not true it stops immediately with:

{ "error": "Status cards are not enabled" }

returned as 404 Not Found. It is an instance-wide switch, not a per-company one, and it gates the API as well as the UI.

You also need the built-in Summarizer agent provisioned and ready for the company, unless the card names its own agent. When neither is available, requests that would start a run fail with 422 Unprocessable Entity, { "error": "Summarizer built-in agent is not configured" }, and a details object carrying code: "summarizer_not_configured" plus the built-in's current status. See Built-in Agents.

Who can call what

Three levels of access show up across these routes:

Agents get one extra restriction on top: an agent may only manage status cards it authored. Managing someone else's returns 403 Forbidden with { "error": "Agents can only manage status cards they authored" }. Reading is unrestricted within the company.

Two hard limits apply to agent callers, from STATUS_CARD_AGENT_MAX_CARDS and STATUS_CARD_AGENT_MAX_INTEREST_PROMPT_LENGTH:

Board callers keep the general 20,000-character limit from the request schema.

A card that is out of reach — another company's, or one that does not exist — is always reported the same way: 404 Not Found with { "error": "Status card not found" }.

The card object

Read routes return cards hydrated with three extra fields the database does not store: summaryBody (the current Markdown), todayTokens and todayCostCents (this card's spend since midnight UTC), and watchedIssueCount (how many issues the compiled query matches right now — omitted if the count could not be computed).

Card states

Refresh policy

refreshPolicy is an object on both create and update:

triggers decides what counts as a change worth an update:

Active hours and the token cap only gate automatic work. A manual refresh or recompile request runs regardless.

List Status Cards

GET /api/companies/{companyId}/status-cards

Return the company's status cards, most recently updated first, each hydrated as described above. Any caller with access to the company may call it.

Example

curl -sS \
  -H "Authorization: Bearer {token}" \
  "https://paperclip.example.com/api/companies/{companyId}/status-cards?archived=false"

Create a Status Card

POST /api/companies/{companyId}/status-cards

Create a card and immediately queue its compile task. Requires tasks:assign.

Request body:

Status code. 201 Created, returning the card as it stands after the compile was queued — state: "compiling" with generatingIssueId set.

Creation and compilation are all-or-nothing: if the compile task cannot be created or the agent cannot be woken, the new card is deleted again and the underlying error is returned.

An agent caller must belong to the company it is creating in; if it does not, the response is 403 Forbidden with { "error": "Agent cannot author status cards for this company" }.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/companies/{companyId}/status-cards" \
  -d '{
    "interestPrompt": "Watch the launch project. Tell me what is blocked and the single next action.",
    "refreshPolicy": {
      "mode": "interval",
      "intervalMinutes": 30,
      "dailyTokenCap": 50000
    }
  }'

Get a Status Card

GET /api/status-cards/{id}

Return one hydrated card. Company access is enough.

Update a Status Card

PATCH /api/status-cards/{id}

Change a card's configuration, or archive and restore it. Requires tasks:assign, and agents may only patch cards they authored.

Request body — at least one field is required, otherwise the request fails validation with "At least one field is required":

Two of these have side effects worth planning for:

• Editing interestPrompt queues a compile task and clears lastUpdateRunKind, so the next content update is a full rebuild rather than a patch. The response is the card returned by that compile.
• Archiving (archived: true) clears nextEvalAt and generatingIssueId and cancels any in-flight generation task. Restoring (archived: false) queues a full refresh with trigger restore, provided the card has compiled queries and nothing is already running.

Changing the agent also clears lastUpdateRunKind, for the same reason: a new writer should not patch text it did not write.

Delete a Status Card

DELETE /api/status-cards/{id}

Permanently delete the card and its update history. Requires tasks:assign, and agents may only delete cards they authored. Responds 204 No Content with an empty body.

Update History

GET /api/status-cards/{id}/updates

Return the card's update ledger, newest first. Company access is enough.

Each entry carries:

changeKind is one of new, removed, status, assignee, human_comment, or updated.

Summary Revisions

GET /api/status-cards/{id}/summary-revisions

Return the card's past summaries, newest first, each with id, revisionNumber, title, body, changeSummary, and createdAt. A card that has never had a summary written returns an empty array. Company access is enough.

Recompile

POST /api/status-cards/{id}/recompile

Rebuild the card's compiled query from its current interestPrompt, then write a fresh full summary. Requires tasks:assign, and agents may only recompile cards they authored.

There is no request body.

Response.

Status codes. A newly queued compile responds 202 Accepted. Joining a compile that was already running responds 200 OK — so pressing the button twice does not queue two runs. A task that is blocked does not count as in flight: it is stuck waiting on a human, so a re-kick reopens it and counts as a fresh run.

Archived cards cannot be compiled: 422 Unprocessable Entity, { "error": "Archived status cards cannot be compiled" }.

Refresh

POST /api/status-cards/{id}/refresh

Ask the card to update now. Requires tasks:assign, and agents may only refresh cards they authored.

Request body:

A manual refresh always runs — it bypasses the card's active-hours window and daily token cap, and it runs even when change detection found nothing new.

Response.

Status codes. 202 Accepted when enqueued is true and alreadyGenerating is false — that is, this request started the run. Everything else is 200 OK: joining a run already in flight, or a policy evaluation that decided to wait, pause, or do nothing.

Two refusals to plan for:

• A card whose query has not compiled yet: 409 Conflict, { "error": "Compile the status-card query before refreshing it" }.
• An archived card: 422 Unprocessable Entity, { "error": "Archived status cards cannot be refreshed" }.

Example

curl -sS -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  "https://paperclip.example.com/api/status-cards/{id}/refresh" \
  -d '{ "full": true }'

Dry Run

GET /api/status-cards/{id}/dry-run

Execute the card's compiled queries right now and return what they match, without writing anything or spending model tokens. This is what the board's Watched issues tab reads.

Unlike the other read routes, this one asks for an explicit company_scope:read decision — a caller confined to a narrower boundary gets 403 Forbidden with { "error": "Status-card dry-run is outside this actor's low-trust authorization boundary" }.

Response.

Write the Compiled Query

PUT /api/status-cards/{id}/query

This is the first of the two endpoints the summarizer agent calls during a compile. It is documented so you can understand what happens to the card — not because you will normally call it yourself.

Request body:

A successful write stores the queries, increments queryVersion, stamps queryCompiledAt and queryCompiledByAgentId, keeps the card in compiling, and records a compile entry in the update ledger — plus a running entry for the full summary that is expected to follow in the same run.

Write the Summary

PUT /api/status-cards/{id}/summary

The endpoint the summarizer agent calls to land a finished summary, whether from a compile or from an update run.

Request body:

The rules both writes have to satisfy

Every one of these failures returns 403 Forbidden:

• The caller must be an agent, and must be either the card's agentId override or an agent carrying the summarizer built-in marker for this company — otherwise { "error": "Only the card's summarizer agent may write status cards" }. Both stay eligible, so a task created before an agent switch can still land its result.
• The write must name the task the card is currently waiting on — { "error": "Status-card write does not match the active generation task" }.
• That task must be assigned to the calling agent — { "error": "Generation task is not assigned to this agent" }.
• It must still be live — { "error": "Generation task is no longer active" }.
• Its payload must target this card and company — { "error": "Generation task does not target this status card" }.
• The request must come from that task's run — { "error": "Status-card write must run from the linked generation task" }.

Conflicts return 409 Conflict: { "error": "Status-card compilation was superseded by a newer task" } on the query write, and { "error": "Status-card generation was superseded by a newer task" } on the summary write.

Archived cards refuse both: 422 Unprocessable Entity, with { "error": "Archived status cards cannot accept generation writes" } for the query and { "error": "Archived status cards cannot accept summaries" } for the summary. A summary write also needs a compiled query first — 409 Conflict, { "error": "Compile the status-card query before writing its summary" }.

What a successful write does

The summary is appended as a new document revision rather than replacing the old text. The card then settles: state returns to active, generatingIssueId and failureReason are cleared, lastGeneratedAt / lastModel / lastUpdateRunKind are stamped, pending-change counters reset, and nextEvalAt is rescheduled from the refresh policy.

Two things happen to the watched set at the same time. Issues the Markdown references — by identifier such as ABC-123, or by an /issues/{uuid} link — are resolved against the card's company and stored in mentionedIssueIds, up to 200, so their later changes trigger updates too. Unknown identifiers and other companies' issues are dropped. And the fingerprint keeps the generation-time baseline for everything else, so an issue that changed while the summary was being written still shows up in the next diff instead of being silently absorbed.

The response contains the updated card, the document, and the new revision. The matching entry in the update ledger is closed out with status: "ok", the run's token and cost totals, and the model.

Response.

Activity logging

Every mutating route records an entry on the company activity log against entityType: "status_card":

See the Activity page for how to read the log.

Where to go next

• Status Cards — the board itself, the update policy explained, and how to turn the feature on.
• Status Card Query skill — the bundled skill that teaches an agent to author cards and compile prompts into queries.
• Built-in Agents — how to provision the Summarizer, and what its lifecycle states mean.
• Summary Slots — the other Summarizer-written surface, fixed to a project or workspace header.
• Issues — compile and update tasks are ordinary issues.
• API Overview — base URL, authentication, company scoping, and the shared error-code table.