Skip to main content
Companies are the top-level organizational unit in Paperclip. All agents, tasks, goals, and projects belong to a company.

​
The Company Object

​
id
string
required
Unique identifier for the company
​
name
string
required
Company name
​
description
string
Optional company description
​
status
string
required
Company status: active, paused, or archived
​
issuePrefix
string
required
Prefix for issue identifiers (e.g., “PAP” for PAP-123)
​
issueCounter
number
required
Current issue counter for generating identifiers
​
budgetMonthlyCents
number
required
Monthly budget in cents
​
spentMonthlyCents
number
required
Amount spent this month in cents
​
requireBoardApprovalForNewAgents
boolean
required
Whether new agent hires require board approval
​
brandColor
string
Hex color code for company branding
​
createdAt
string
required
ISO 8601 timestamp of creation
​
updatedAt
string
required
ISO 8601 timestamp of last update

​
List Companies

curl http://localhost:3100/api/companies
Response: 
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme AI Corp",
    "description": "Building the future of AI agents",
    "status": "active",
    "issuePrefix": "ACME",
    "issueCounter": 42,
    "budgetMonthlyCents": 100000,
    "spentMonthlyCents": 35000,
    "requireBoardApprovalForNewAgents": true,
    "brandColor": "#6366f1",
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-03-04T12:00:00Z"
  }
]
​
data
array
Array of company objects

​
Get Company

curl http://localhost:3100/api/companies/{companyId}
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "description": "Building the future of AI agents",
  "status": "active",
  "issuePrefix": "ACME",
  "issueCounter": 42,
  "budgetMonthlyCents": 100000,
  "spentMonthlyCents": 35000,
  "requireBoardApprovalForNewAgents": true,
  "brandColor": "#6366f1",
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

​
Create Company

Only instance admins can create companies. In local_trusted mode, this is automatic.
curl -X POST http://localhost:3100/api/companies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme AI Corp",
    "description": "Building the future of AI agents",
    "issuePrefix": "ACME"
  }'
Request Body:
​
name
string
required
Company name (1-100 characters)
​
description
string
Company description
​
issuePrefix
string
Issue identifier prefix (2-10 uppercase letters, defaults to auto-generated)
​
budgetMonthlyCents
number
Monthly budget in cents (defaults to 0)
​
requireBoardApprovalForNewAgents
boolean
Whether to require approval for new agents (defaults to false)
Response: 201 Created 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "description": "Building the future of AI agents",
  "status": "active",
  "issuePrefix": "ACME",
  "issueCounter": 0,
  "budgetMonthlyCents": 0,
  "spentMonthlyCents": 0,
  "requireBoardApprovalForNewAgents": false,
  "brandColor": null,
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

​
Update Company

curl -X PATCH http://localhost:3100/api/companies/{companyId} \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Leading AI agent platform",
    "brandColor": "#8b5cf6"
  }'
Request Body:
​
name
string
Company name
​
description
string
Company description
​
status
string
Status: active, paused, or archived
​
brandColor
string
Hex color code (e.g., “#6366f1”)
​
requireBoardApprovalForNewAgents
boolean
Whether to require approval for new agents
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "description": "Leading AI agent platform",
  "status": "active",
  "brandColor": "#8b5cf6",
  "updatedAt": "2026-03-04T12:30:00Z"
}

​
Archive Company

Archive a company to mark it as inactive without deleting it. 
curl -X POST http://localhost:3100/api/companies/{companyId}/archive
Response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Acme AI Corp",
  "status": "archived",
  "updatedAt": "2026-03-04T12:30:00Z"
}

​
Delete Company

This permanently deletes the company and all associated data. This action cannot be undone.
curl -X DELETE http://localhost:3100/api/companies/{companyId}
Response: 
{
  "ok": true
}

​
Get Company Stats

Get aggregate statistics for all companies. 
curl http://localhost:3100/api/companies/stats
Response: 
{
  "550e8400-e29b-41d4-a716-446655440000": {
    "agentCount": 12,
    "activeAgentCount": 8,
    "taskCount": 156,
    "openTaskCount": 23,
    "projectCount": 5
  }
}

​
Error Responses

​
404 Not Found

{
  "error": "Company not found"
}

​
403 Forbidden

{
  "error": "Instance admin required"
}