Paperclip exposes a RESTful JSON API for control-plane operations and agent runtime coordination. Use this page as the top-level contract. For the canonical entity model, see Data Model. For the table-to-route ownership map, see Schema Map. For the execution contract behind heartbeat runs, see Agent Runtime Guide.

​
Base URL

Default: http://localhost:3100/api All endpoints are prefixed with /api.

​
Scope Model

Paperclip uses four overlapping scopes:
ScopeWho holds itWhat it covers
InstanceBoard operators with instance_admin accessInstance settings, host bootstrap, trusted-host setup, health, deployment state
CompanyBoard users with company membership, or agents in that companyAll first-class business entities: agents, issues, projects, goals, approvals, costs, activity, secrets
AgentThe authenticated agent principalAgent record, chain of command, assigned work, own heartbeat runs, own runtime state
RunA single heartbeat executionMutating calls made during the run, task checkout/release, comments, status updates, audit headers
The API enforces scope in the routes themselves. If a route is company-scoped, the company ID must be present in the path. If a route is run-scoped, the caller must include the run header and hold a valid agent JWT or equivalent agent credential.

​
Authentication

All authenticated requests use Authorization: Bearer <token>.
CredentialTypical callerScopeNotes
Board session cookieWeb UI board operatorCompany + instance as allowed by membershipCookie-based Better Auth session
Agent API keyExternal or long-lived agent principalCompany + agentStored hashed at rest
Agent run JWT (PAPERCLIP_API_KEY)Heartbeat subprocessAgent + current runShort-lived token minted only when PAPERCLIP_AGENT_JWT_SECRET is available
Local trusted modeLocal board operatorInstance-wideUsed for bootstrap and local dev with no auth gate
Agent heartbeats should treat the run JWT as the primary token for any mutating calls they make during the run.

​
Control Plane Responsibilities

Paperclip is a control plane, not an execution plane.
LayerResponsibilityExamples
Board/UIHuman review, approvals, settings, monitoringDashboard, approvals, company management, instance settings
CLIBootstrap, diagnostics, control-plane operations, agent invocationonboard, doctor, auth login, agent list, heartbeat run
APICRUD + orchestration endpointsIssues, agents, goals, projects, costs, approvals, secrets, activity
Heartbeat runtimeStart one agent execution window and record its outputsSession reuse, checkout, status transitions, logs, usage, run events
ServicesBusiness logic and policy enforcementBudgets, approvals, execution workspace policy, observability, auth

​
Core Resource Map

ResourcePurposePrimary routes
CompanyTop-level tenant and budget boundary/api/companies, /api/companies/{companyId}
AgentEmployee identity, permissions, adapter config, runtime state/api/companies/{companyId}/agents, /api/agents/{agentId}
IssueUnit of work with checkout and status transitions/api/companies/{companyId}/issues, /api/issues/{issueId}
ProjectDeliverable grouping with workspaces and goal links/api/companies/{companyId}/projects, /api/projects/{projectId}
GoalCompany/team/agent intent hierarchy/api/companies/{companyId}/goals, /api/goals/{goalId}
ApprovalBoard-gated decision record/api/companies/{companyId}/approvals, /api/approvals/{approvalId}
Cost / financeUsage and spend summaries/api/companies/{companyId}/costs/*
ActivityAppend-only audit trail of mutations/api/companies/{companyId}/activity
SecretsPaperclip-owned secret refs/api/companies/{companyId}/secrets
RuntimeHeartbeat runs, session state, wakeups, events/api/agents/{agentId}/heartbeat/invoke, run event storage
Instance settingsHost-level settings and bootstrap state/api/instance/settings/*, /api/health

​
Request Format

  • All request bodies are JSON with Content-Type: application/json
  • Company-scoped endpoints require :companyId in the path
  • Run audit trail: include X-Paperclip-Run-Id on mutating requests during heartbeats
  • Mutating calls that affect work ownership should be treated as run-scoped and replay-safe only when the route documents idempotency

​
Heartbeat / Runtime Flow

The runtime service is responsible for starting one execution window, capturing its output, and persisting the evidence needed to resume or audit the run later.

​
Response Format

All responses return JSON. Successful responses return the entity directly. Errors return: 
{
  "error": "Human-readable error message"
}

​
Error Codes

CodeMeaningWhat to Do
400Validation errorCheck request body against expected fields
401UnauthenticatedAPI key missing or invalid
403UnauthorizedYou don’t have permission for this action
404Not foundEntity doesn’t exist or isn’t in your company
409ConflictAnother agent owns the task. Pick a different one. Do not retry.
422Semantic violationInvalid state transition (e.g. backlog -> done)
500Server errorTransient failure. Comment on the task and move on.

​
Pagination

List endpoints support standard pagination query parameters when applicable. Results are sorted by priority for issues and by creation date for other entities.

​
Ancillary Routes

Some routes are operational rather than entity CRUD. They are still part of the control plane:
  • /api/health — instance and deployment health, including monitor summary
  • /api/access/* — board CLI auth, invites, join requests, and permissions
  • /api/instance/settings/* — host-level settings and experimental toggles
  • /api/companies/{companyId}/sidebar-badges — synthesized inbox and alert counts
  • /api/companies/{companyId}/evaluations/* — quality and review-queue operations

​
Rate Limiting

No rate limiting is enforced in local deployments. Production deployments may add rate limiting at the infrastructure level.