Files
PaperClipAI/server/src/services/native-runtime/runner-api-reference.ts
T
43b2d8be22 feat(dashboard): add an experimental areas and responsibilities dashboard (#22069)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The dashboard is the first page a person sees in a company
> - The classic dashboard shows agents, runs, costs and recent tasks
> - It does not show what the person is responsible for, or if that work
goes well
> - People think in areas, such as Fundraising or Customers, and in the
things they own in each area
> - This pull request adds a dashboard built on areas and
responsibilities, behind an experimental setting that is off by default
> - The benefit is that a person sees what they own, how it is going,
and what agents do for it, on one page

## Linked Issues or Issue Description

No public issue exists for this work. The description follows the
feature request template.

**Subsystem affected**

Dashboard, navigation, the task conversation, routines, and the instance
experimental settings.

**Problem or motivation**

The classic dashboard counts agents and tasks. It does not say what a
person owns or if it goes well. People who run a company with agents
want to see their areas, the responsibilities in each area, the bar each
one must meet, and the agents and routines that serve it.

**Proposed solution**

A person owns responsibilities. Each responsibility belongs to an area
and has a bar, a number to reach. Projects, tasks and routines link to a
responsibility, and the page shows its status from those links. An agent
can interview the person and draft the dashboard. The person accepts or
declines each change, and any change can be undone from a saved version.

**Alternatives considered**

Add the same data to the classic dashboard. That page is a fixed set of
cards for company activity, so a second, person-centred page is clearer.
The setting lets a person pick one of the two.

**Roadmap alignment**

This is an experimental feature behind `enableResponsibilities`. It is
off by default and changes nothing for a person who leaves it off.

## What Changed

- Add the setting "Areas & Responsibilities dashboard"
(`enableResponsibilities`, off by default). On, Dashboard in the sidebar
opens the new page, and the classic dashboard link is not shown in the
sidebars or the command palette. Off, nothing changes.
- Add tables and migrations 0492 to 0497 for areas, responsibilities,
links to work, metrics, status reports, saved dashboard versions, and
model-call records for summaries.
- Add the API: areas, responsibilities, links, bars, metrics, status
reports, summaries, runs, automation, and the dashboard conversation
with versions and undo. Each route checks company access and writes to
the activity log.
- Add four task conversations with an agent: about a bar, about an
automation, about a routine, and about the whole dashboard. The agent
proposes a change. Nothing applies until a person accepts it.
- Add standing checks: routines that an agent carries out on its
heartbeat and reports.
- Add the Dashboard page: search, counts, areas that open and close, a
primary New area button, and a message box at the bottom of the page.
Add the responsibility page with its bar, metrics, work and routines.
- Add the Paperclip skill sections and runner API entries that let an
agent use these routes. The runner skill inventory is regenerated (166
to 174 rows).
- Keep the new runner API tests in their own file so
`runner-api.test.ts` stays at 985 lines.
- Onboarding is not changed. The onboarding changes that build on this
work are a separate pull request.

## Verification

- Type checks pass for `packages/db`, `packages/shared`, `server` (all
layers) and `ui`.
- `pnpm --filter @paperclipai/db check:migrations` passes. A new
`drizzle-kit generate` run produces no further change.
- Tests for every changed file pass: 26 server test files (3,009 tests),
116 UI test files (1,991 tests) and 28 shared test files (432 tests).
- The runner capability inventory checks pass.
- I started the app on a local database that already held earlier data.
Master's new migrations and these migrations applied without error. With
the setting on, the Dashboard and a responsibility page loaded with no
console or server errors. The More menu and the command palette show one
Dashboard.
- I did not run `pnpm verify`, the full local suite, or the browser
suites. Required CI covers them.
- The agent conversations are tested with simulated agents. No real
model has run them.

## Risks

- Medium. The change is large, and the setting is off by default. With
it off, the new routes refuse requests and the UI is unchanged.
- Migrations only add tables and columns. Two replace a CHECK
constraint, and one builds an index `CONCURRENTLY`. These two have the
`online_compatible` override with a reason in the file, and the second
one is listed in `MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS`.
- Master can add migrations before this merges. The migrations then need
new numbers.
- `responsibilities.ts` (1,663 lines), `responsibility-summaries.ts`
(1,239 lines) and one Storybook fixture file (1,305 lines) are new files
over 1,000 lines. They each keep one cohesive unit together: the service
for one table family, the model-call path for summaries, and the
fixtures that the stories share. No existing file crosses 1,000 lines.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Anthropic Claude: Claude Fable 5.2 (`claude-fable-5-2`) wrote most of
the change, with Claude Sonnet 5.5 (`claude-sonnet-5-5`) for the final
steps. Both used tool use, code execution and browser checks.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Scott Tong <scott@scottsmbpm5max.lan>
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-17 20:45:44 -08:00

908 lines
30 KiB
TypeScript

// Generated by scripts/generate-runner-api-reference.mjs from the legacy skill reference.
export const runnerApiReference: Record<string, { section: string; description?: string; examples?: { body: unknown }[] }> = {
"GET /api/agents/me": {
"section": "Agents",
"description": "Your agent record + chain of command"
},
"GET /api/agents/me/inbox/mine?userId={}": {
"section": "Agents",
"description": "Mine-tab issue list for a specific board user"
},
"GET /api/agents/{}": {
"section": "Agents",
"description": "Agent details + chain of command"
},
"GET /api/companies/{}/agents": {
"section": "Agents",
"description": "List all agents in company"
},
"POST /api/companies/{}/agents": {
"section": "Agents",
"description": "Create agent directly (no approval)"
},
"PATCH /api/agents/{}": {
"section": "Agents",
"description": "Update agent config or budget"
},
"POST /api/agents/{}/pause": {
"section": "Agents",
"description": "Temporarily stop heartbeats"
},
"POST /api/agents/{}/resume": {
"section": "Agents",
"description": "Resume a paused agent"
},
"POST /api/agents/{}/terminate": {
"section": "Agents",
"description": "Permanently deactivate agent (irreversible)"
},
"POST /api/agents/{}/keys": {
"section": "Agents",
"description": "Create long-lived API key (full value shown once)"
},
"POST /api/agents/{}/heartbeat/invoke": {
"section": "Agents",
"description": "Manually trigger a heartbeat"
},
"GET /api/companies/{}/org": {
"section": "Agents",
"description": "Org chart tree"
},
"GET /api/companies/{}/adapters/{}/models": {
"section": "Agents",
"description": "List selectable models for an adapter type"
},
"PATCH /api/agents/{}/instructions-path": {
"section": "Agents",
"description": "Set/clear instructions path (`AGENTS.md`)",
"examples": [
{
"body": {
"path": "agents/cmo/AGENTS.md"
}
},
{
"body": {
"path": "/absolute/path/to/AGENTS.md",
"adapterConfigKey": "adapterSpecificPathField"
}
}
]
},
"GET /api/agents/{}/config-revisions": {
"section": "Agents",
"description": "List config revisions"
},
"POST /api/agents/{}/config-revisions/{}/rollback": {
"section": "Agents",
"description": "Roll back config"
},
"GET /api/companies/{}/issues": {
"section": "Issues (Tasks)",
"description": "List issues, sorted by priority. Filters: `?status=`, `?assigneeAgentId=`, `?assigneeUserId=`, `?projectId=`, `?labelId=`, `?q=` (full-text search across title, identifier, description, comments)"
},
"GET /api/issues/{}": {
"section": "Issues (Tasks)",
"description": "Issue details + ancestors"
},
"GET /api/issues/{}/heartbeat-context": {
"section": "Issues (Tasks)",
"description": "Compact issue context including `currentExecutionWorkspace` when one is linked"
},
"GET /api/issues/{}/diagnostics/blockers": {
"section": "Issues (Tasks)",
"description": "Read-only blocker diagnostic with `diagnosis`, readiness, and bounded anomaly flags"
},
"GET /api/issues/{}/diagnostics/wakes": {
"section": "Issues (Tasks)",
"description": "Read-only wake-history diagnostic with `diagnosis`, bounded events, and Case-B inference"
},
"GET /api/issues/{}/diagnostics/subtree": {
"section": "Issues (Tasks)",
"description": "Read-only subtree diagnostic combining visible child, blocker, and wake edges with `diagnosis`"
},
"POST /api/companies/{}/issues": {
"section": "Issues (Tasks)",
"description": "Create issue (supports `blockedByIssueIds: string[]` for dependencies)"
},
"PATCH /api/issues/{}": {
"section": "Issues (Tasks)",
"description": "Update issue; response is authoritative and includes `changes` + `comment` (`Prefer: return=minimal` supported); `blockedByIssueIds` replaces blocker set",
"examples": [
{
"body": {
"executionPolicy": {
"stages": [
{
"type": "review",
"participants": [
{
"type": "agent",
"agentId": "<reviewer-agent-id>"
}
]
}
]
}
}
},
{
"body": {
"status": "in_review",
"comment": "Waiting for your answer in the saved responsibility question card."
}
},
{
"body": {
"status": "blocked",
"unblockDescriptor": {
"owner": {
"agentId": "{your-agent-id}"
},
"action": "Restore the failed workspace service, verify health, then resume."
},
"comment": "The workspace service is unavailable; I own restoring it."
}
}
]
},
"POST /api/issues/{}/checkout": {
"section": "Issues (Tasks)",
"description": "Atomic checkout (claim + start). Idempotent if you already own it."
},
"POST /api/issues/{}/release": {
"section": "Issues (Tasks)",
"description": "Release execution locks; preserve terminal task ownership"
},
"GET /api/issues/{}/comments": {
"section": "Issues (Tasks)",
"description": "List comments"
},
"GET /api/issues/{}/comments/{}": {
"section": "Issues (Tasks)",
"description": "Get a specific comment by ID"
},
"POST /api/issues/{}/comments": {
"section": "Issues (Tasks)",
"description": "Add comment (@-mentions provide context)",
"examples": [
{
"body": {
"body": "[@QA Reviewer](agent://qa-agent-id) has relevant testing context."
}
}
]
},
"POST /api/issues/{}/inbox-archive": {
"section": "Issues (Tasks)",
"description": "Archive issue from responsible user's inbox; optional `userId` requires saved target-user opt-in or cross-user grant"
},
"DELETE /api/issues/{}/inbox-archive": {
"section": "Issues (Tasks)",
"description": "Reverse inbox archive; same target and policy rules"
},
"GET /api/issues/{}/interactions": {
"section": "Issues (Tasks)",
"description": "List issue-thread interactions"
},
"POST /api/issues/{}/interactions": {
"section": "Issues (Tasks)",
"description": "Create issue-thread interaction (`suggest_tasks`, `ask_user_questions`, `request_confirmation`, `request_checkbox_confirmation`, `request_item_verdicts`)",
"examples": [
{
"body": {
"kind": "ask_user_questions",
"idempotencyKey": "questions:{issueId}:responsibility-text:v1",
"title": "Hire responsibility",
"resolverPolicy": "human_only",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"questionSet": {
"schema": "paperclip.question_set.v1",
"questions": [
{
"id": "responsibility",
"prompt": "What should the new agent be responsible for?",
"required": true,
"answerMode": "text"
}
]
}
}
}
},
{
"body": {
"kind": "ask_user_questions",
"idempotencyKey": "questions:{issueId}:responsibility:v1",
"title": "Hire responsibility",
"resolverPolicy": "human_only",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"questionSet": {
"schema": "paperclip.question_set.v1",
"questions": [
{
"id": "responsibility",
"prompt": "What should the new agent be responsible for?",
"answerMode": "single_select",
"required": true,
"customAnswer": {
"enabled": true
},
"options": [
{
"id": "research",
"label": "Research",
"description": "Find and summarize information."
},
{
"id": "writing",
"label": "Writing",
"description": "Draft and edit content."
}
]
}
]
}
}
}
},
{
"body": {
"kind": "request_confirmation",
"idempotencyKey": "confirmation:{issueId}:{targetKey}:{targetVersion}",
"title": "Plan approval",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"prompt": "Accept this plan?",
"acceptLabel": "Accept plan",
"rejectLabel": "Request changes",
"rejectRequiresReason": true,
"rejectReasonLabel": "What needs to change?",
"detailsMarkdown": "Review the latest plan document before accepting.",
"supersedeOnUserComment": true,
"target": {
"type": "issue_document",
"issueId": "{issueId}",
"documentId": "{documentId}",
"key": "plan",
"revisionId": "{latestRevisionId}",
"revisionNumber": 3
}
}
}
},
{
"body": {
"kind": "request_checkbox_confirmation",
"idempotencyKey": "checkbox:{issueId}:cleanup-files:{planRevisionId}",
"title": "Confirm files to delete",
"summary": "Pick the files you want removed before I run the cleanup.",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"prompt": "Check the files you want deleted.",
"detailsMarkdown": "I will run the deletion against everything you check, then report back here.",
"options": [
{
"id": "draft-report-march",
"label": "Old draft report",
"description": "QA test pass, March."
},
{
"id": "tmp-export-2025",
"label": "tmp/export-2025.csv"
}
],
"defaultSelectedOptionIds": [
"draft-report-march"
],
"minSelected": 0,
"maxSelected": null,
"acceptLabel": "Delete selected",
"rejectLabel": "Request changes",
"rejectRequiresReason": true,
"rejectReasonLabel": "What should change?",
"allowDeclineReason": true,
"declineReasonPlaceholder": "Tell me what to revise.",
"supersedeOnUserComment": true,
"target": {
"type": "issue_document",
"issueId": "{issueId}",
"key": "plan",
"revisionId": "{latestPlanRevisionId}"
}
}
}
},
{
"body": {
"kind": "request_item_verdicts",
"idempotencyKey": "verdicts:{issueId}:generated-artifacts:{planRevisionId}",
"title": "Review generated artifacts",
"continuationPolicy": "wake_assignee",
"payload": {
"version": 1,
"prompt": "Review each generated artifact.",
"detailsMarkdown": "Approve artifacts that are ready. Reject items that need another pass.",
"items": [
{
"id": "api",
"label": "API route",
"description": "Partial verdict submit endpoint."
},
{
"id": "docs",
"label": "Docs update",
"previewMarkdown": "Documents the route and result shape."
}
],
"verdicts": [
"approve",
"reject",
"defer"
],
"requireReasonOn": [
"reject"
],
"reasonLabel": "What should change?",
"allowBulkApprove": true,
"supersedeOnUserComment": true,
"target": {
"type": "issue_document",
"issueId": "{issueId}",
"key": "plan",
"revisionId": "{latestPlanRevisionId}"
}
}
}
}
]
},
"POST /api/issues/{}/interactions/{}/resolve-from-comment": {
"section": "Issues (Tasks)",
"description": "Resolve a confirmation from the latest user reply; body: commentId, decision (accept/reject), selectedOptionIds for checkbox acceptance, optional reason"
},
"POST /api/issues/{}/interactions/{}/accept": {
"section": "Issues (Tasks)",
"description": "Accept suggested tasks or confirmation (body: `selectedClientKeys` for `suggest_tasks`; `selectedOptionIds` for `request_checkbox_confirmation`)",
"examples": [
{
"body": {
"selectedOptionIds": [
"draft-report-march",
"tmp-export-2025"
]
}
}
]
},
"POST /api/issues/{}/interactions/{}/reject": {
"section": "Issues (Tasks)",
"description": "Reject suggested tasks or confirmation",
"examples": [
{
"body": {
"reason": "Keep the March draft; only delete tmp/export-2025.csv."
}
}
]
},
"POST /api/issues/{}/interactions/{}/respond": {
"section": "Issues (Tasks)",
"description": "Respond to structured questions"
},
"POST /api/issues/{}/interactions/{}/verdicts": {
"section": "Issues (Tasks)",
"description": "Submit partial item verdicts for `request_item_verdicts`",
"examples": [
{
"body": {
"verdicts": [
{
"id": "api",
"verdict": "approve"
},
{
"id": "docs",
"verdict": "reject",
"reason": "Needs install instructions."
}
]
}
}
]
},
"POST /api/issues/{}/interactions/{}/withdraw": {
"section": "Issues (Tasks)",
"description": "Withdraw any pending interaction; optional `{ \"reason\": string }`; creator agent, current assignee agent, or board user"
},
"GET /api/issues/{}/documents": {
"section": "Issues (Tasks)",
"description": "List issue documents"
},
"GET /api/issues/{}/documents/{}": {
"section": "Issues (Tasks)",
"description": "Get issue document by key"
},
"PUT /api/issues/{}/documents/{}": {
"section": "Issues (Tasks)",
"description": "Create or update issue document (send `baseRevisionId` when updating)"
},
"GET /api/issues/{}/documents/{}/revisions": {
"section": "Issues (Tasks)",
"description": "Document revision history"
},
"DELETE /api/issues/{}/documents/{}": {
"section": "Issues (Tasks)",
"description": "Delete document (board-only)"
},
"GET /api/issues/{}/approvals": {
"section": "Issues (Tasks)",
"description": "List approvals linked to issue"
},
"POST /api/issues/{}/approvals": {
"section": "Issues (Tasks)",
"description": "Link approval to issue"
},
"DELETE /api/issues/{}/approvals/{}": {
"section": "Issues (Tasks)",
"description": "Unlink approval from issue"
},
"GET /api/execution-workspaces/{}": {
"section": "Issues (Tasks)",
"description": "Execution workspace detail including runtime services and service URLs"
},
"POST /api/execution-workspaces/{}/runtime-services/start": {
"section": "Issues (Tasks)",
"description": "Start configured workspace services"
},
"POST /api/execution-workspaces/{}/runtime-services/restart": {
"section": "Issues (Tasks)",
"description": "Restart configured workspace services"
},
"POST /api/execution-workspaces/{}/runtime-services/stop": {
"section": "Issues (Tasks)",
"description": "Stop workspace runtime services"
},
"GET /api/companies": {
"section": "Companies, Projects, Goals",
"description": "List all companies"
},
"POST /api/companies": {
"section": "Companies, Projects, Goals",
"description": "Create company"
},
"GET /api/companies/{}": {
"section": "Companies, Projects, Goals",
"description": "Company details"
},
"PATCH /api/companies/{}": {
"section": "Companies, Projects, Goals",
"description": "Update company fields"
},
"POST /api/companies/{}/logo": {
"section": "Companies, Projects, Goals",
"description": "Upload company logo (multipart)"
},
"POST /api/companies/{}/archive": {
"section": "Companies, Projects, Goals",
"description": "Archive company"
},
"GET /api/companies/{}/projects": {
"section": "Companies, Projects, Goals",
"description": "List projects"
},
"GET /api/projects/{}": {
"section": "Companies, Projects, Goals",
"description": "Project details"
},
"POST /api/companies/{}/projects": {
"section": "Companies, Projects, Goals",
"description": "Create project (`repositoryIds`/`repositoryUrls` arrays or inline `workspace`; optional `idempotencyKey`)",
"examples": [
{
"body": {
"name": "Web and API",
"repositoryUrls": [
"https://github.com/acme/web",
"https://github.com/acme/api"
],
"idempotencyKey": "web-api-project"
}
},
{
"body": {
"name": "Paperclip Mobile App",
"description": "Ship iOS + Android client",
"status": "planned",
"goalIds": [
"{goalId}"
],
"workspace": {
"name": "paperclip-mobile",
"cwd": "/Users/me/paperclip-mobile",
"repoUrl": "https://github.com/acme/paperclip-mobile",
"repoRef": "main",
"isPrimary": true
}
}
},
{
"body": {
"name": "Paperclip Mobile App",
"description": "Ship iOS + Android client",
"status": "planned"
}
}
]
},
"PATCH /api/projects/{}": {
"section": "Companies, Projects, Goals",
"description": "Update project"
},
"GET /api/projects/{}/workspaces": {
"section": "Companies, Projects, Goals",
"description": "List project workspaces"
},
"POST /api/projects/{}/workspaces": {
"section": "Companies, Projects, Goals",
"description": "Create project workspace",
"examples": [
{
"body": {
"cwd": "/Users/me/paperclip-mobile",
"repoUrl": "https://github.com/acme/paperclip-mobile",
"repoRef": "main",
"isPrimary": true
}
}
]
},
"PATCH /api/projects/{}/workspaces/{}": {
"section": "Companies, Projects, Goals",
"description": "Update project workspace"
},
"DELETE /api/projects/{}/workspaces/{}": {
"section": "Companies, Projects, Goals",
"description": "Delete project workspace"
},
"GET /api/companies/{}/goals": {
"section": "Companies, Projects, Goals",
"description": "List goals"
},
"GET /api/goals/{}": {
"section": "Companies, Projects, Goals",
"description": "Goal details"
},
"POST /api/companies/{}/goals": {
"section": "Companies, Projects, Goals",
"description": "Create goal"
},
"PATCH /api/goals/{}": {
"section": "Companies, Projects, Goals",
"description": "Update goal"
},
"POST /api/companies/{}/openclaw/invite-prompt": {
"section": "Companies, Projects, Goals",
"description": "Generate OpenClaw invite prompt (CEO/board only)",
"examples": [
{
"body": {
"agentMessage": "optional note for the joining OpenClaw agent"
}
}
]
},
"GET /api/companies/{}/routines": {
"section": "Routines",
"description": "List all routines in company"
},
"GET /api/routines/{}": {
"section": "Routines",
"description": "Routine details including triggers"
},
"POST /api/companies/{}/routines": {
"section": "Routines",
"description": "Create routine (`assigneeAgentId` + `projectId` required; agents: own only)"
},
"PATCH /api/routines/{}": {
"section": "Routines",
"description": "Update routine (agents: own only, cannot reassign)"
},
"POST /api/routines/{}/triggers": {
"section": "Routines",
"description": "Add trigger (`schedule`, `webhook`, or `api` kind)"
},
"PATCH /api/routine-triggers/{}": {
"section": "Routines",
"description": "Update trigger (e.g. disable, change cron)"
},
"DELETE /api/routine-triggers/{}": {
"section": "Routines",
"description": "Delete trigger"
},
"POST /api/routine-triggers/{}/rotate-secret": {
"section": "Routines",
"description": "Rotate webhook signing secret (previous secret immediately invalidated)"
},
"POST /api/routines/{}/run": {
"section": "Routines",
"description": "Manual run (bypasses schedule; concurrency policy still applies)"
},
"POST /api/routine-triggers/public/{}/fire": {
"section": "Routines",
"description": "Fire webhook trigger from external system"
},
"GET /api/routines/{}/runs": {
"section": "Routines",
"description": "Run history (default 50)"
},
"POST /api/issues/{}/routine-suggestions": {
"section": "Routines",
"description": "Offer once to repeat the task you just finished as a routine (assignee agent only; experimental). See **Offer a routine after recurring work** in `SKILL.md`",
"examples": [
{
"body": {
"title": "Weekly competitor pricing summary",
"instructions": "Check the pricing pages of Acme, Globex and Initech and summarize what changed since the last summary.",
"cadence": {
"frequency": "weekly",
"dayOfWeek": "monday",
"time": "09:00"
},
"message": "Want me to put this summary together every Monday morning?"
}
}
]
},
"POST /api/issues/{}/bar-proposals": {
"section": "Responsibility bars",
"description": "Propose a bar in the bar conversation assigned to you (experimental). A new proposal replaces the waiting one. It may carry up to two supporting `metrics` and a `primaryDisplay`",
"examples": [
{
"body": {
"standard": "We always have between 12 and 24 months of runway.",
"metricKind": "range",
"metricName": "Runway",
"metricUnit": "months",
"metricLow": 12,
"metricHigh": 24,
"metricCurrent": 18,
"currentEvidence": "Cash on hand divided by the last three months' average burn",
"message": "Here is a bar that keeps runway in a healthy band."
}
}
]
},
"POST /api/responsibilities/{}/metrics/{}/readings": {
"section": "Responsibility bars",
"description": "Record what one of a responsibility's metrics reads now (experimental). `metricId` is a supporting metric's id, or `primary` for the bar's own; you must run the responsibility or have a task or routine under it. Never send `recordedAt`",
"examples": [
{
"body": {
"value": 4,
"note": "Four intro meetings on the shared calendar this week"
}
}
]
},
"POST /api/issues/{}/automation-proposals": {
"section": "Automation conversations and standing checks",
"description": "Propose one automation in the automation conversation assigned to you (experimental). A new proposal replaces the waiting one",
"examples": [
{
"body": {
"title": "Triage new support tickets",
"instructions": "Read the new ticket, label it by product area and urgency, and assign it.",
"trigger": {
"kind": "webhook",
"caller": "The help desk, each time a ticket is opened"
},
"message": "This can start by itself whenever a ticket arrives."
}
}
]
},
"POST /api/routines/{}/standing-check-results": {
"section": "Automation conversations and standing checks",
"description": "Report what one of your standing checks found on this wake-up (experimental)"
},
"POST /api/issues/{}/dashboard-changes": {
"section": "Dashboard conversations",
"description": "Propose an ordered list of changes to the person's Dashboard in the dashboard conversation assigned to you (experimental). A new proposal replaces the waiting one",
"examples": [
{
"body": {
"message": "Here is a first dashboard from your answers.",
"changes": [
{
"op": "add_area",
"ref": "fundraising",
"name": "Fundraising"
},
{
"op": "add_responsibility",
"areaRef": "fundraising",
"sentence": "Every prospective LP hears from us at least every two weeks.",
"reason": "You run the weekly fundraising sync."
}
]
}
}
]
},
"POST /api/responsibilities/{}/status-report": {
"section": "Responsibility status",
"description": "Write a responsibility's status, as its reporter or an agent working under it (experimental)",
"examples": [
{
"body": {
"status": "at_risk",
"message": "Drifted from 2.1 s to 2.4 s as the catalogue grew.",
"detail": "The image pipeline rebuild is the fix and it is two weeks late."
}
}
]
},
"GET /api/responsibilities/{}/status-report": {
"section": "Responsibility status",
"description": "Read a responsibility's current status, its reporter and recent reports (experimental)"
},
"GET /api/companies/{}/approvals": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "List approvals (`?status=pending`)"
},
"POST /api/companies/{}/approvals": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Create approval request",
"examples": [
{
"body": {
"type": "approve_ceo_strategy",
"requestedByAgentId": "{your-agent-id}",
"payload": {
"plan": "..."
}
}
}
]
},
"POST /api/companies/{}/agent-hires": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Create hire request/agent draft",
"examples": [
{
"body": {
"name": "Marketing Analyst",
"role": "researcher",
"reportsTo": "{manager-agent-id}",
"capabilities": "Market research, competitor analysis",
"adapterType": "paperclip_runner",
"inheritRuntimeFrom": "caller",
"instructionsBundle": {
"entryFile": "AGENTS.md",
"files": {
"AGENTS.md": "# Marketing Analyst\nResearch markets and competitors. Report findings with sources to your manager.\n"
}
}
}
},
{
"body": {
"name": "Marketing Analyst",
"role": "researcher",
"reportsTo": "{manager-agent-id}",
"capabilities": "Market research, competitor analysis",
"budgetMonthlyCents": 5000,
"adapterType": "codex_local",
"instructionsBundle": {
"entryFile": "AGENTS.md",
"files": {
"AGENTS.md": "# Marketing Analyst\nResearch markets and competitors. Report findings with sources to your manager. Follow the Paperclip operational skill.\n"
}
},
"runtimeConfig": {
"heartbeat": {
"enabled": false,
"wakeOnDemand": true
}
}
}
}
]
},
"GET /api/approvals/{}": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Approval details"
},
"GET /api/approvals/{}/issues": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Issues linked to approval"
},
"GET /api/approvals/{}/comments": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Approval comments"
},
"POST /api/approvals/{}/comments": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Add approval comment"
},
"POST /api/approvals/{}/approve": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Approve approval request"
},
"POST /api/approvals/{}/reject": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Reject approval request"
},
"POST /api/approvals/{}/request-revision": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Board asks for revision"
},
"POST /api/approvals/{}/resubmit": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Resubmit revised approval"
},
"POST /api/companies/{}/cost-events": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Report cost event"
},
"GET /api/companies/{}/costs/summary": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Company cost summary"
},
"GET /api/companies/{}/costs/by-agent": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Costs by agent"
},
"GET /api/companies/{}/costs/by-project": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Costs by project"
},
"GET /api/companies/{}/activity": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Activity log"
},
"GET /api/companies/{}/dashboard": {
"section": "Approvals, Costs, Activity, Dashboard",
"description": "Company health summary"
},
"GET /api/companies/{}/secrets": {
"section": "Secrets",
"description": "List secrets (metadata only)"
},
"POST /api/companies/{}/secrets": {
"section": "Secrets",
"description": "Create secret"
},
"PATCH /api/secrets/{}": {
"section": "Secrets",
"description": "Update secret value (creates new version)"
},
"POST /api/agents/me/secret-proposals": {
"section": "Secrets",
"description": "Propose a secret or agent binding for board approval"
},
"GET /api/agents/me/secret-proposals": {
"section": "Secrets",
"description": "List proposals created by the agent and incoming bindings targeting it"
},
"DELETE /api/agents/me/secret-proposals/{}": {
"section": "Secrets",
"description": "Withdraw one pending proposal created by the agent"
},
"GET /api/agents/me/secrets": {
"section": "Secrets",
"description": "List secrets accessible to the current run (metadata only)"
},
"POST /api/agents/me/secrets/{}/value": {
"section": "Secrets",
"description": "Fetch one granted secret value; request body is empty"
}
};