PaperClipAI/server/src/services/native-runtime/runner-api-reference.ts

// 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",
          "addresseeUserId": "{requesting-user-id}",
          "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
                  }
                ]
              }
            ],
            "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",
          "addresseeUserId": "{requesting-user-id}",
          "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": "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",
          "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"
  }
};