mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-24 10:13:11 +02:00
DottaandPaperclip
7e6d512597
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The first agent helps the board define work and hire other agents. > - That agent can have the general role while its instructions require hiring skills. > - Missing skills and blocked schema discovery make valid requests fail. > - Repeated confirmation and invalid waiting guidance can turn these failures into extra runs. > - This PR supplies the required skills, opens read-only schema discovery, and corrects the guidance. > - The agent can complete an authorized hire while company approval and duplicate checks still apply. ## Linked Issues or Issue Description Refs #13068 — the first-task onboarding flow that this change repairs. Refs #12029 — related drift between the sandbox allowlist and bundled hiring guidance. This PR adds schema access; it does not replace the earlier hiring-route fix. **What happened?** A general-role onboarding chief received hiring instructions without the core hiring skills. Sandbox requests to the documented OpenAPI endpoint failed. The agent then guessed question and hire payloads. The persona required new confirmation after validation errors and described waiting states that agents cannot set. **Expected behavior** A direct request authorizes the requested hire. The chief asks only for material missing details, uses valid API payloads, and completes the task. Formal company approval gates still apply. A saved human-input card gives the task a valid waiting state. **Steps to reproduce** 1. Create an onboarding chief with role `general` through the board. 2. Ask it to hire a friendly robot with a supplied name and responsibilities. 3. Check its assigned skills, schema requests, question cards, hire requests, and final task state. **Paperclip version or commit** Reproduced on the first-task onboarding implementation after #13068. The live local verification used this branch at `112f44610`. **Deployment mode** The original failure used a hosted sandbox with legacy Codex ACP. Live verification used an isolated local instance and real `codex_local` execution. Queue and HTTP/2 transport access is covered by automated tests. ## What Changed - Give board-created onboarding chiefs the existing core skills regardless of role. Preserve explicit skill version pins, including aliases. Keep ordinary general-agent defaults and authorization checks. - Allow exactly `GET /api/openapi.json` through both sandbox bridge transports. - Publish validator-tested question, free-text, hire, and waiting examples. Regenerate the runner API reference and capability inventory. - Clarify direct authorization, material ambiguity, and correction of confirmed pre-creation validation failures. Preserve uncertain-outcome reconciliation, duplicate protection, and company approval gates. - Align disposition instructions with agent permissions and the saved human-input waiting path. ## Verification - After rebasing onto current `master`: 69 targeted server tests, 110 queue/HTTP2 bridge tests, and 4 capability inventory tests passed. These cover core skill defaults, version pins, actor restrictions, schema access, published examples, hire validation, idempotency, and approval gates. Waiting recovery tests and live question flows also passed before the rebase. - `pnpm -r typecheck` and `pnpm build` passed again after the rebase. Frozen dependency installation and both generated capability checks passed. - Ran the full `pnpm test:run` suite. The initial run had 14 failed server files due to local database resource limits, a missing built test fixture, and socket failures. All 14 files passed after fixture repair and isolated retries. UI, CLI, workspace packages, database tests, and all 145 serialized server files passed. - Real one-request hiring replay: one hire, one successful run, task done in 2m16s. No repeated approval or recovery escalation. - Real two-turn browser conversation: start with an unspecified hire, then supply a name and friendly robot responsibilities. One clarification card, one hire, two successful runs, task done in 3m27s of execution. No failed writes, confirmation cards, or recovery actions. - Assigned the hired robot a welcome-message task through the browser. It produced a warm message under 100 words and finished in one successful 66-second run, with no questions or recovery actions. - The two-turn flow still asked an optional preferences question and gave a technical final reply. These are remaining presentation limits. - Greptile: 5/5 on `b71f83ba2`, with zero unresolved review threads. Fixed its generator finding and passed 1,655 published-example/runtime API tests plus server typecheck. All latest-head CI checks are green (32 passed; 2 unrelated Storybook checks skipped). The signoff-policy browser test initially timed out while waiting for an approver run. Its shard passed on one rerun without code changes. [CI run](https://github.com/paperclipai/paperclip/actions/runs/34698211049). ## Risks - Onboarding chiefs receive more default skills. Ordinary general agents retain existing defaults, and explicit versions take precedence. - Prompt guidance can affect model behavior. The live replays are examples, not a guarantee that every model follows the guidance. - Retry guidance applies only when validation confirms that nothing was created. Uncertain outcomes still require checking existing agents. - No database migration or new public endpoint. Existing company boundaries, approval gates, and bounded recovery remain in force. ## Model Used OpenAI Codex, model `gpt-6-astra`, with reasoning, tool use, code editing, and live browser verification. The exact context-window size is not exposed in this session. ## 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 - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
776 lines
25 KiB
TypeScript
776 lines
25 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 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 trigger wakeups)",
|
|
"examples": [
|
|
{
|
|
"body": {
|
|
"body": "[@QA Reviewer](agent://qa-agent-id) please review this implementation."
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"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:v1",
|
|
"title": "Hire responsibility",
|
|
"resolverPolicy": "human_only",
|
|
"continuationPolicy": "wake_assignee",
|
|
"payload": {
|
|
"version": 1,
|
|
"questions": [
|
|
{
|
|
"id": "responsibility",
|
|
"prompt": "What should the new agent be responsible for?",
|
|
"selectionMode": "single",
|
|
"required": true,
|
|
"allowOther": true,
|
|
"options": [
|
|
{
|
|
"id": "research",
|
|
"label": "Research",
|
|
"description": "Find and summarize information."
|
|
},
|
|
{
|
|
"id": "writing",
|
|
"label": "Writing",
|
|
"description": "Draft and edit content."
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"body": {
|
|
"kind": "ask_user_questions",
|
|
"idempotencyKey": "questions:{issueId}:responsibility-text:v1",
|
|
"title": "Hire responsibility",
|
|
"resolverPolicy": "human_only",
|
|
"continuationPolicy": "wake_assignee",
|
|
"payload": {
|
|
"version": 1,
|
|
"questions": [
|
|
{
|
|
"id": "responsibility",
|
|
"prompt": "What should the new agent be responsible for?",
|
|
"selectionMode": "single",
|
|
"required": true,
|
|
"options": [
|
|
{
|
|
"id": "describe",
|
|
"label": "I'll describe it",
|
|
"freeText": true
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"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/{}/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)"
|
|
},
|
|
"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",
|
|
"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"
|
|
}
|
|
};
|