Companies

Create and manage companies in Paperclip

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

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

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

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

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

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

curl -X DELETE http://localhost:3100/api/companies/{companyId}

Response:

{
  "ok": true
}

---

Get Company Stats

Get aggregate statistics for all companies.

cURL

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"
}