Paperclip Governance and REST API: Control, Budgets, and Isolation

Running a single AI agent in isolation is straightforward. Running dozens of agents across multiple teams, business units, or client companies — each with different budgets, permissions, and data access — is an entirely different engineering challenge. This is where Paperclip’s governance layer separates itself from lightweight orchestration tools.

This article covers Paperclip’s governance model in depth: how budget controls prevent runaway costs, how role hierarchies determine who can instruct which agents, how multi-company isolation keeps tenant data strictly separated, and how the REST API enables programmatic control over the entire system. You will also get a deep dive into the heartbeat protocol that keeps task state consistent across distributed agent fleets.

If you have not yet set up Paperclip, start with the installation guide before proceeding. For context on how Paperclip compares to other multi-agent frameworks, see CrewAI vs AutoGen.

Paperclip’s Governance Model

Most multi-agent frameworks treat governance as an afterthought — a layer you bolt on after building the core orchestration logic. Paperclip inverts this: governance is a first-class architectural concept, baked into every API call, every agent spawn, and every task assignment.

The governance model rests on three pillars:

Organizational hierarchy. Paperclip models your organization as a tree of companies (tenants), departments, and individual agents. Every resource — tasks, files, API keys, memory stores — is owned by a node in this tree. Access flows downward through the hierarchy with explicit grants required to cross boundaries.

Budget enforcement. Every agent has a spending envelope. Every company has an aggregate cap. Costs are tracked in real time against these envelopes, and hard limits halt execution before overruns occur. Soft limits trigger notifications, giving humans a chance to intervene before the hard cap is reached.

Audit-by-default. Every state transition — task creation, agent assignment, budget deduction, permission check — writes an immutable audit log entry. You cannot disable this. The audit log is the source of truth for compliance reviews, cost attribution, and incident forensics.

What makes this different from a typical multi-agent setup like AutoGen or a hand-rolled CrewAI workflow? Those frameworks give you agents and communication channels. Paperclip gives you agents and communication channels plus a control plane that enforces organizational policy at runtime. An agent cannot spend money it was not allocated. An agent cannot read data outside its tenant boundary. An agent cannot be hired without a role assignment from a principal with sufficient authority.

This matters most in three scenarios: regulated industries where auditability is mandatory, consulting or SaaS businesses serving multiple clients from a single agent fleet, and large organizations where individual teams own their own budgets and data.

Budget Controls

Paperclip budget controls operate at two levels: the individual agent level and the company (tenant) level. Both use the same underlying accounting system, so company-level caps are always the sum of activity across all agents in that company.

Agent-Level Budget Configuration

When you hire an agent, you attach a budget object to the hire request:

{
  "name": "research-agent-01",
  "role": "researcher",
  "model": "claude-3-5-sonnet-20241022",
  "budget": {
    "currency": "USD",
    "soft_limit": 5.00,
    "hard_limit": 10.00,
    "period": "monthly",
    "reset_day": 1,
    "notify_channels": ["slack:#ai-ops", "email:[email protected]"],
    "notify_threshold_pct": 80
  }
}

Key fields explained:

• soft_limit — When cumulative spend in the current period crosses this value, Paperclip fires notifications to notify_channels but does not stop the agent.
• hard_limit — When cumulative spend crosses this value, Paperclip refuses to dispatch new LLM calls for this agent. In-flight calls complete; new calls fail with 402 Budget Exceeded.
• period — Either daily, weekly, monthly, or rolling_30d. Rolling windows are recalculated hourly.
• reset_day — For monthly periods, the day of month (1–28) on which the budget resets.
• notify_threshold_pct — Notification fires when (current_spend / soft_limit) * 100 exceeds this value.

Company-Level Budget Configuration

Company budgets are set via the admin API and function as an aggregate ceiling across all agents in the company:

{
  "company_id": "comp_8f3a2b",
  "budget": {
    "currency": "USD",
    "monthly_cap": 500.00,
    "alert_at": 400.00,
    "alert_channels": ["email:[email protected]"],
    "overage_policy": "halt_new_tasks"
  }
}

overage_policy accepts three values:

Real-Time Cost Tracking

Paperclip tracks costs at token granularity. Every LLM response includes token counts in provider-standard metadata. Paperclip’s cost engine applies your configured cost-per-token rates for each model:

# Query current spend for an agent
curl -X GET "https://api.paperclip.example/v1/agents/agt_9x1m4r/budget/current" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

{
  "agent_id": "agt_9x1m4r",
  "period": "monthly",
  "period_start": "2026-04-01T00:00:00Z",
  "current_spend_usd": 3.47,
  "soft_limit_usd": 5.00,
  "hard_limit_usd": 10.00,
  "pct_of_soft": 69.4,
  "status": "within_budget",
  "last_updated": "2026-04-08T14:22:11Z"
}

Role Permissions and Hierarchy

Paperclip ships with a default role hierarchy modeled after a software engineering organization. Roles determine which API endpoints an agent can call, which agents it can hire or fire, and which tasks it can create or modify.

Default Role Definitions

The Observer role is particularly useful for human oversight integrations — dashboards, compliance tooling, and external monitoring systems can be granted Observer access without any write permissions.

Role Assignment

Roles are assigned at hire time and can be modified by principals with sufficient authority:

# Hire a new PM agent
curl -X POST "https://api.paperclip.example/v1/agents/hire" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-manager-alice",
    "role": "PM",
    "company_id": "comp_8f3a2b",
    "department": "platform-team",
    "model": "claude-3-5-sonnet-20241022",
    "system_prompt": "You are a product manager focused on developer tooling...",
    "budget": {
      "soft_limit": 20.00,
      "hard_limit": 40.00,
      "period": "monthly"
    }
  }'

Custom Role Definitions

If the default roles do not map cleanly to your organization, you can define custom roles with fine-grained permission lists:

{
  "role_name": "data-steward",
  "company_id": "comp_8f3a2b",
  "permissions": [
    "tasks:read",
    "tasks:create",
    "tasks:update:own",
    "agents:read",
    "budget:read",
    "audit_log:read",
    "data:read:company",
    "data:write:department"
  ],
  "hire_authority": [],
  "fire_authority": [],
  "max_budget_grant_usd": 0
}

Permission strings follow the pattern resource:action[:scope]. Scopes can be own, department, or company.

Permission Inheritance

Paperclip uses additive permission inheritance. Child roles inherit all permissions of their parent but can never exceed parent authority. A CTO cannot grant a PM hire authority over roles that the CTO itself cannot hire — the system enforces this at request time, not at configuration time.

Multi-Company Isolation

For consulting firms, SaaS platforms, or any organization managing multiple clients with a single Paperclip deployment, multi-company isolation is the feature that makes the architecture safe.

Data Isolation Guarantees

Each company in Paperclip is a strict tenant boundary:

• Task isolation. Tasks created under company_id: comp_A are invisible to all agents in comp_B, regardless of role.
• Memory isolation. Each company’s vector store and conversation history is namespaced by company ID at the storage layer, not just filtered at query time.
• File isolation. Files uploaded or generated by agents in one company cannot be referenced by agents in another company without an explicit cross-company share grant (which requires CEO-level authority on both sides).
• Secret isolation. API keys, credentials, and environment variables stored in Paperclip’s secret vault are scoped per company.

Creating a Company Tenant

curl -X POST "https://api.paperclip.example/v1/companies" \
  -H "Authorization: Bearer $PAPERCLIP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme",
    "plan": "business",
    "budget": {
      "monthly_cap_usd": 500.00,
      "overage_policy": "halt_new_tasks"
    },
    "data_region": "us-east-1",
    "isolation_level": "strict"
  }'

isolation_level accepts two values:

• strict — Full tenant isolation. No cross-company data access, even with explicit grants. Recommended for regulated industries.
• managed — Allows cross-company share grants. Suitable for internal multi-team deployments where some data sharing is intentional.

Cross-Company Communication

In managed mode, agents can communicate across company boundaries through a controlled message-passing channel. Direct memory or file access across companies is still prohibited; only structured task messages can cross the boundary, and only when a cross-company channel has been established by an admin:

# Create a cross-company channel (admin only)
curl -X POST "https://api.paperclip.example/v1/channels" \
  -H "Authorization: Bearer $PAPERCLIP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-to-globex-handoff",
    "source_company_id": "comp_8f3a2b",
    "target_company_id": "comp_c4d5e6",
    "allowed_task_types": ["handoff", "status_update"],
    "message_schema": "strict",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The REST API

Paperclip exposes a comprehensive REST API over HTTPS. All endpoints return JSON and use standard HTTP status codes. Authentication uses bearer tokens issued per agent or per admin user.

Core Endpoint Reference

Agent Management

Task Management

Budget and Billing

Governance and Audit

Practical cURL Examples

List all active agents with their current task:

curl -X GET "https://api.paperclip.example/v1/agents?status=active&include=current_task" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  | jq '.agents[] | {id, name, role, current_task: .current_task.title}'

Create a task and assign it to a specific agent:

curl -X POST "https://api.paperclip.example/v1/tasks" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyze Q1 competitor pricing changes",
    "description": "Review all major competitor pricing pages and summarize changes since January 2026. Include impact analysis for our mid-market tier.",
    "assigned_to": "agt_9x1m4r",
    "priority": "high",
    "deadline": "2026-04-09T18:00:00Z",
    "tags": ["competitive-intel", "pricing"],
    "require_approval": false
  }'

Query audit log for a specific agent over the past 7 days:

curl -X GET "https://api.paperclip.example/v1/audit-log" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -G \
  --data-urlencode "agent_id=agt_9x1m4r" \
  --data-urlencode "from=2026-04-01T00:00:00Z" \
  --data-urlencode "to=2026-04-08T23:59:59Z" \
  --data-urlencode "event_types=task_started,task_completed,budget_alert,permission_denied"

Update an agent’s hard budget limit:

curl -X PUT "https://api.paperclip.example/v1/agents/agt_9x1m4r/budget" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hard_limit": 15.00,
    "reason": "Approved increase for Q2 research sprint"
  }'

Pagination and Filtering

All list endpoints support cursor-based pagination:

# First page
curl "https://api.paperclip.example/v1/tasks?limit=20&status=completed" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

# Next page using cursor from previous response
curl "https://api.paperclip.example/v1/tasks?limit=20&status=completed&cursor=eyJpZCI6MTIzfQ==" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

Response envelopes always include pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 847,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTIzfQ=="
  }
}

Heartbeat Protocol Deep Dive

The heartbeat protocol is Paperclip’s mechanism for maintaining reliable task state across long-running agent executions. Without it, a task executing for 45 minutes with no signal would be indistinguishable from a crashed agent — and the system would not know whether to wait, retry, or reassign.

How Heartbeats Work

When an agent picks up a task, it enters a contract: it must emit a heartbeat signal at regular intervals for as long as the task is running. The default interval is 30 seconds, configurable per agent:

{
  "heartbeat": {
    "interval_seconds": 30,
    "timeout_multiplier": 3,
    "on_timeout": "reassign"
  }
}

timeout_multiplier defines how many missed heartbeats before the system considers the task orphaned. With interval_seconds: 30 and timeout_multiplier: 3, a task is declared timed out after 90 seconds of silence.

Heartbeat Payload

Agents send heartbeats via a POST to the task heartbeat endpoint:

curl -X POST "https://api.paperclip.example/v1/tasks/tsk_7k2p9q/heartbeat" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "progress_pct": 42,
    "current_step": "Fetching competitor pricing pages",
    "steps_completed": ["Initialize browser context", "Identify target URLs"],
    "steps_remaining": ["Extract pricing data", "Normalize formats", "Generate summary"],
    "estimated_completion": "2026-04-08T15:45:00Z",
    "spend_usd_since_last_heartbeat": 0.12
  }'

The spend_usd_since_last_heartbeat field is how the cost accounting system maintains real-time accuracy — agents self-report incremental costs, and the server reconciles these against provider invoices at the end of each billing period.

Task State Machine

A task moves through the following states:

created → queued → assigned → in_progress → (completed | failed | cancelled | timed_out)
                                  ↑                          |
                                  └──────── reassigned ←──────┘ (if on_timeout = reassign)

State transitions are only valid in the directions shown. An agent cannot move a task from completed back to in_progress, and only the control plane (not individual agents) can move tasks to timed_out or reassigned.

Handling Timeouts and Failures

When a task times out, the on_timeout policy determines what happens next:

For tasks that fail due to unhandled exceptions in agent code, the agent should explicitly report the failure before terminating:

curl -X POST "https://api.paperclip.example/v1/tasks/tsk_7k2p9q/complete" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "failed",
    "error_code": "TOOL_UNAVAILABLE",
    "error_message": "Browser automation tool returned 503 after 3 retries",
    "partial_result": {
      "pages_processed": 4,
      "pages_failed": 2
    },
    "retry_recommended": true
  }'

Explicitly failing a task rather than letting it time out is strongly preferred — it preserves partial results, gives the system accurate failure reasons for dashboards, and avoids the delay introduced by waiting for the timeout window to expire.

Security Considerations

API Authentication

Paperclip issues three types of API tokens, each with different scope and lifetime:

Task tokens are the most secure option for agent code — they expire automatically when the task ends and have no authority beyond the current task. Use them for all agent-to-API calls during task execution:

import os
import httpx

# Task token injected by Paperclip runtime at task start
task_token = os.environ["PAPERCLIP_TASK_TOKEN"]
task_id = os.environ["PAPERCLIP_TASK_ID"]

client = httpx.Client(
    base_url="https://api.paperclip.example/v1",
    headers={"Authorization": f"Bearer {task_token}"}
)

# This call succeeds — reading own task is within task token scope
response = client.get(f"/tasks/{task_id}")

# This call fails — task tokens cannot list other agents
response = client.get("/agents")  # 403 Forbidden

Agent Sandboxing

Beyond API-level authentication, Paperclip recommends sandboxing agent execution environments:

• Run each agent in a separate container or VM with no network access except to the Paperclip API and explicitly whitelisted external endpoints.
• Mount filesystems read-only except for a designated scratch directory that is wiped after task completion.
• Use ephemeral compute — spawn a container for each task, destroy it on completion. Never reuse execution environments across tasks from different companies.

Audit Logging

Every API request generates an audit log entry with the following fields:

{
  "log_id": "alog_k3m7p",
  "timestamp": "2026-04-08T14:22:11.432Z",
  "event_type": "task_created",
  "actor_type": "agent",
  "actor_id": "agt_9x1m4r",
  "actor_role": "PM",
  "company_id": "comp_8f3a2b",
  "resource_type": "task",
  "resource_id": "tsk_7k2p9q",
  "action": "create",
  "outcome": "success",
  "ip_address": "10.0.0.42",
  "request_id": "req_f9g2h1",
  "changes": {
    "before": null,
    "after": { "status": "queued", "priority": "high" }
  }
}

Audit logs are append-only and cannot be modified or deleted through the API — not even by admin tokens. They are retained for 90 days by default, with configurable retention up to 7 years for compliance plans.

To export audit logs for your SIEM or compliance tooling:

# Export audit log as NDJSON for a date range
curl -X GET "https://api.paperclip.example/v1/audit-log/export" \
  -H "Authorization: Bearer $PAPERCLIP_ADMIN_KEY" \
  -G \
  --data-urlencode "from=2026-04-01T00:00:00Z" \
  --data-urlencode "to=2026-04-08T23:59:59Z" \
  --data-urlencode "format=ndjson" \
  -o audit-2026-04-08.ndjson

Frequently Asked Questions

How does Paperclip handle rate limiting?

Paperclip enforces rate limits at two levels. At the API gateway level, each token is subject to request-per-minute and request-per-day limits configurable per role — admin tokens have higher limits than agent tokens, and task tokens are limited to endpoints relevant to the current task. At the LLM provider level, Paperclip’s cost engine tracks not just spend but also token-per-minute consumption against each provider’s rate limits, and will queue LLM calls rather than forward them when a provider limit is about to be hit. You can inspect current rate limit headroom via GET /v1/agents/{agent_id}/rate-limits.

Can I set up webhook callbacks for agent events?

Yes. Paperclip supports outbound webhooks for any event type in the audit log. Register a webhook endpoint via the API, specify the event types you want to receive, and Paperclip will POST a signed payload to your endpoint whenever a matching event occurs:

curl -X POST "https://api.paperclip.example/v1/webhooks" \
  -H "Authorization: Bearer $PAPERCLIP_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example/hooks/paperclip",
    "events": ["task_completed", "task_failed", "budget_alert", "agent_hired"],
    "company_id": "comp_8f3a2b",
    "secret": "whsec_your_signing_secret"
  }'

Payloads are signed with HMAC-SHA256 using the secret you provide. Verify the X-Paperclip-Signature header on incoming requests to confirm authenticity. Paperclip retries failed webhook deliveries with exponential backoff for up to 24 hours.

Is it possible to create custom roles beyond the defaults?

Yes, and this is fully supported for managed isolation mode. Use the POST /v1/roles endpoint with a permissions array as described in the Role Permissions section. Custom roles can be as narrow or as broad as needed, but they cannot exceed the authority of the role belonging to the token making the creation request — a CTO cannot create a custom role with CEO-level permissions. For strict isolation mode, custom role creation requires admin-key authorization.

What compliance standards does Paperclip support?

Paperclip’s audit log retention, data isolation architecture, and access control model are designed to support SOC 2 Type II, ISO 27001, and GDPR compliance programs. The immutable audit log satisfies logging requirements for all three. Data residency controls (the data_region field on company creation) allow you to pin tenant data to specific AWS regions to meet GDPR data sovereignty requirements. For HIPAA, Paperclip offers a Business Associate Agreement (BAA) on enterprise plans, along with enhanced encryption at rest using customer-managed KMS keys. Note that compliance certification is your responsibility — Paperclip provides the controls, but you must implement the policies and procedures around them.

Next Steps

With governance, budgets, and the REST API under your belt, you have the foundation to run a production-grade Paperclip deployment. Here is where to go from here:

• Build a custom agent. The patterns from AutoGPT Forge’s custom agent guide translate directly to Paperclip’s agent model — read it for battle-tested patterns around tool use, memory management, and error recovery.

• Compare orchestration approaches. If you are evaluating whether Paperclip’s governance model is the right fit versus a code-first framework, the CrewAI vs AutoGen comparison gives you a structured framework for making that call.

• Set up monitoring. Wire Paperclip webhooks to your existing observability stack — Datadog, Grafana, or a custom dashboard — so you get real-time visibility into agent activity, cost burn rate, and task completion rates without manually polling the API.

• Automate budget reviews. Write a lightweight Python script that queries /v1/companies/{id}/budget/current on a schedule and posts a weekly cost summary to your team’s Slack channel. This closes the loop between automated agent activity and human financial oversight.

• Stress test isolation. Before going to production with multiple client tenants, write integration tests that verify cross-company data isolation holds under concurrent load. Attempt reads across company boundaries from agent tokens and assert that all such requests return 403 Forbidden.

The governance model described in this article is what elevates Paperclip from a developer toy to a production infrastructure component. Use it rigorously from day one — retrofitting governance onto a running agent fleet is significantly harder than designing for it upfront.