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

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:

{
  "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:

{
  "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.