mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 12:04:41 +01:00
DottaandPaperclip
5bddff0920
## Thinking Path > - Paperclip manages AI agents and their work. > - The new runner gives agents dedicated tools for common tasks. > - Some API operations and parameters have no dedicated tool. > - Agents need a controlled way to find and use those operations. > - This pull request adds API search and calls through the real server routes. > - Existing tools remain the preferred path. The new tools are disabled by default. > - Paired tests measure correctness, tool choice, cost and time. ## Linked Issues or Issue Description **Subsystem affected** Paperclip Runner contracts, production tool authority and the server API catalog. **Problem or motivation** The runner cannot use much of the API described by the old Paperclip skill. A generic HTTP client would also let agents bypass runner control rules. **Proposed solution** Add `search_api` and `call_api`. Resolve calls from the mounted API catalog. Use server-held, run-bound credentials. Preserve route checks and runner lifecycle rules. Keep the tools disabled until an operator enables selected companies. **Alternatives considered** A dedicated tool for every endpoint would add a large initial prompt. An unrestricted HTTP tool would weaken authorization and replay controls. **Roadmap alignment** This extends the native runner tooling. The repository owner requested this design and implementation. The roadmap and related open PRs were checked. No duplicate API escape-hatch PR was found. ## What Changed - Register two compact fallback tools in canonical contracts and provider projections. - Build deterministic API discovery from OpenAPI, mounted experimental routes and the old skill reference. - Execute bounded JSON, text, file and download requests through authenticated HTTP routes. - Recheck active runs, company access and work modes. Block runner lifecycle, scheduling, credential and approval bypasses. Keep routine annotation collaboration available. - Retain mutation receipts. Report uncertain outcomes without blindly repeating writes. - Add a company rollout gate and a durable eval worker with complete cost accounting checks. - Record child-task creation in the activity log with the agent and run. - Add contract, authorization, file, replay and real runnerd/PRP/HTTP tests. - Document rollout gates and paid coverage limits. The companion eval repository retains immutable attempts and reports. ## Verification - Final app commit `da58370524c3626a744eec20164397c5fb6ba9ef`: all 32 checks passed; the unrelated Storybook visual check was skipped. Greptile 5/5; no unresolved review threads. - Full Linux build and recursive typecheck passed. Repository tests were run by project and serialized shard; all 143 serialized server suites passed. - Runner TypeScript: 1,599 passed, two skipped. Rust release: 451 passing test reports. Conformance and replay parity passed. The required API check passed 837 tests, including runnerd → PRP → authority → real HTTP. - Bindings cannot enable API tools without the explicit deployment flag. Unit and real-authority tests prove the default-off boundary. - The standalone API check builds and stages its own binary. It passed after existing staged and debug binaries were removed from the test container. - UI and CLI tests passed. Initial environment failures (missing jq, Docker overlay file identity, and parallel linker memory pressure) and focused passing reruns are retained. The macOS full runner suite has platform-specific failures; Linux is the qualified full-check platform. - Eval harness: 27 tests passed; existing CI discovery ran 86 tests with two unrelated skips. Credential export rejection is tested against the actual report command. - Luna and OpenRouter Sonnet each passed 60 common-workflow runs: ten workflows, three repetitions per arm, zero unnecessary API fallback. - Sonnet passed 11 selected capability/contract cases after fixes. Gemini passed three smoke cases. DeepSeek exceeded the 120-second limit and remains unqualified. - Luna's two cost flags received focused follow-up. The original flags and a later n=1 latency flag remain visible. Sonnet had no cost or latency increase above 20%. - The catalog contains 785 entries; 58 were exercised across all stages. Most operation probes remain unrun and some need additional fixtures. Authored probes do not establish successful coverage. - Total conservative accounted cost: $9.875960. Active paid-campaign time: 88.16/90 minutes. No missing accounting. Later security and harness fixes have provider-free verification; no paid validation is claimed for those revisions. - Inspect the [qualification report](https://github.com/paperclipai/paperclip-evals/blob/codex/seach-call-api-tools/evals/runner-api-tools/reports/2026-09-07-production/READINESS.md) and [verification record](https://github.com/paperclipai/paperclip-evals/blob/codex/seach-call-api-tools/evals/runner-api-tools/reports/2026-09-07-production/verification.json). ## Risks - This is a broad authenticated API surface. Keep the default-off gate until an operator selects initial rollout companies. - Paid coverage is incomplete. Small regression samples do not prove all workflows are unchanged. - A timeout or server failure can follow a committed mutation. The result reports an unknown outcome and requires state inspection. - The new definitions add prompt tokens. The report retains cost flags and cache variation. - No database migration is required. - Repository rules require code-owner approval before merge. Technical CI and automated review are complete. ## Model Used OpenAI Codex based on GPT-6 assisted with code, tests and review. The exact serving model ID and context window are not exposed in this session. It used reasoning, tool calls and code execution. Eval models: `gpt-5.6-luna` with low reasoning, `openrouter/anthropic/claude-sonnet-5`, `openrouter/google/gemini-3.8-flash`, and `openrouter/deepseek/deepseek-v4-flash-0731`. Attempts retain runtime versions, model identity, usage and source provenance. ## 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>
690 lines
22 KiB
TypeScript
690 lines
22 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>"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"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)"
|
|
},
|
|
"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": "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`)"
|
|
},
|
|
"POST /api/issues/{}/interactions/{}/reject": {
|
|
"section": "Issues (Tasks)",
|
|
"description": "Reject suggested tasks or confirmation"
|
|
},
|
|
"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 (optional inline `workspace`)",
|
|
"examples": [
|
|
{
|
|
"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)"
|
|
},
|
|
"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"
|
|
},
|
|
"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
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"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"
|
|
},
|
|
"POST /api/companies/company-1/imports/preview": {
|
|
"section": "Worked example",
|
|
"examples": [
|
|
{
|
|
"body": {
|
|
"source": {
|
|
"type": "github",
|
|
"url": "https://github.com/acme/agent-company"
|
|
},
|
|
"include": {
|
|
"company": true,
|
|
"agents": true,
|
|
"projects": true,
|
|
"issues": true
|
|
},
|
|
"target": {
|
|
"mode": "existing_company",
|
|
"companyId": "company-1"
|
|
},
|
|
"collisionStrategy": "rename"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"POST /api/companies/company-1/imports/apply": {
|
|
"section": "Worked example",
|
|
"examples": [
|
|
{
|
|
"body": {
|
|
"source": {
|
|
"type": "github",
|
|
"url": "https://github.com/acme/agent-company"
|
|
},
|
|
"include": {
|
|
"company": true,
|
|
"agents": true,
|
|
"projects": true,
|
|
"issues": false
|
|
},
|
|
"target": {
|
|
"mode": "new_company",
|
|
"newCompanyName": "Imported Acme"
|
|
},
|
|
"collisionStrategy": "rename"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"POST /api/companies/company-1/exports/preview": {
|
|
"section": "Worked example",
|
|
"examples": [
|
|
{
|
|
"body": {
|
|
"include": {
|
|
"company": true,
|
|
"agents": true,
|
|
"projects": true
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"POST /api/companies/company-1/exports": {
|
|
"section": "Worked example",
|
|
"examples": [
|
|
{
|
|
"body": {
|
|
"include": {
|
|
"company": true,
|
|
"agents": true,
|
|
"projects": true,
|
|
"issues": true
|
|
},
|
|
"selectedFiles": [
|
|
"COMPANY.md",
|
|
"agents/ceo/AGENTS.md",
|
|
"skills/paperclip/SKILL.md",
|
|
"tasks/pap-42/TASK.md"
|
|
]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
};
|