skills to all

skills/paperclip-create-agent/references/api-reference.md

@@ -0,0 +1,95 @@
+# Paperclip Create Agent API Reference
+
+## Core Endpoints
+
+- `GET /llms/agent-configuration.txt`
+- `GET /llms/agent-configuration/:adapterType.txt`
+- `GET /llms/agent-icons.txt`
+- `GET /api/companies/:companyId/agent-configurations`
+- `GET /api/agents/:agentId/configuration`
+- `POST /api/companies/:companyId/agent-hires`
+- `GET /api/agents/:agentId/config-revisions`
+- `POST /api/agents/:agentId/config-revisions/:revisionId/rollback`
+- `POST /api/issues/:issueId/approvals`
+- `GET /api/approvals/:approvalId/issues`
+
+Approval collaboration:
+
+- `GET /api/approvals/:approvalId`
+- `POST /api/approvals/:approvalId/request-revision` (board)
+- `POST /api/approvals/:approvalId/resubmit`
+- `GET /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/comments`
+- `GET /api/approvals/:approvalId/issues`
+
+## `POST /api/companies/:companyId/agent-hires`
+
+Request body matches agent create shape:
+
+```json
+{
+  "name": "CTO",
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "uuid-or-null",
+  "capabilities": "Owns architecture and engineering execution",
+  "adapterType": "claude_local",
+  "adapterConfig": {
+    "cwd": "/absolute/path",
+    "model": "claude-sonnet-4-5-20250929",
+    "promptTemplate": "You are CTO..."
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "budgetMonthlyCents": 0,
+  "sourceIssueId": "uuid-or-null",
+  "sourceIssueIds": ["uuid-1", "uuid-2"]
+}
+```
+
+Response:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "pending_approval"
+  },
+  "approval": {
+    "id": "uuid",
+    "type": "hire_agent",
+    "status": "pending"
+  }
+}
+```
+
+If company setting disables required approval, `approval` is `null` and the agent is created as `idle`.
+
+## Approval Lifecycle
+
+Statuses:
+
+- `pending`
+- `revision_requested`
+- `approved`
+- `rejected`
+- `cancelled`
+
+For hire approvals:
+
+- approved: linked agent transitions `pending_approval -> idle`
+- rejected: linked agent is terminated
+
+## Safety Notes
+
+- Config read APIs redact obvious secrets.
+- `pending_approval` agents cannot run heartbeats, receive assignments, or create keys.
+- All actions are logged in activity for auditability.
+- Use markdown in issue/approval comments and include links to approval, agent, and source issue.
+- After approval resolution, requester may be woken with `PAPERCLIP_APPROVAL_ID` and should reconcile linked issues.