The companies resource is the root of every other resource. Teams, agents, tasks, budgets, and audit events all hang off a company.

​
Endpoints

MethodPathPurpose
GET/v1/companiesList companies
POST/v1/companiesCreate a company
GET/v1/companies/{id}Get one company
PATCH/v1/companies/{id}Update a company
POST/v1/companies/{id}/archiveArchive (soft delete)
POST/v1/companies/{id}/restoreRestore an archived company
DELETE/v1/companies/{id}Hard delete (admin only)

​
The company object

{
  "id": "cmp_a1b2c3",
  "slug": "ampha-group",
  "name": "Ampha Group",
  "description": "Accounting firm in Sandton, South Africa",
  "defaultAdapter": "claude-code",
  "fiscalPeriod": "monthly",
  "budget": {
    "usd": 500,
    "period": "monthly",
    "reservePercent": 20
  },
  "teamCount": 4,
  "agentCount": 12,
  "status": "active",
  "createdAt": "2026-03-01T09:00:00Z",
  "updatedAt": "2026-04-11T08:14:22Z"
}
Fields:
  • slug — URL-safe identifier, unique per instance
  • defaultAdapter — which adapter newly hired agents default to
  • fiscalPeriod — daily, weekly, monthly, or quarterly
  • budget — top-line budget for the current period, including the reserve split
  • teamCount/agentCount — denormalized counts, updated on every team/agent change
  • status — active, archived, or deleting

​
List companies

curl -s http://localhost:3100/v1/companies \
  -H "Authorization: Bearer $CA_API_TOKEN"
Query parameters:
  • status — filter by active (default) or archived
  • cursor — pagination cursor from a previous response
  • limit — page size (1 to 200, default 50)

​
Create a company

curl -s http://localhost:3100/v1/companies \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ampha Group",
    "slug": "ampha-group",
    "description": "Accounting firm in Sandton, South Africa",
    "defaultAdapter": "claude-code",
    "fiscalPeriod": "monthly",
    "budget": {
      "usd": 500,
      "period": "monthly",
      "reservePercent": 20
    },
    "startingTeams": [
      { "name": "Engineering", "headcount": 3 },
      { "name": "Design", "headcount": 2 },
      { "name": "Operations", "headcount": 2 }
    ]
  }'
The startingTeams field is optional. If provided, the response includes the created teams and an initial set of empty agent slots. Errors:
  • slug_in_use — another company has the same slug
  • budget_invalid — reserve percent out of range, or USD less than zero
  • adapter_not_installed — the default adapter is not on this instance

​
Get a company

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3 \
  -H "Authorization: Bearer $CA_API_TOKEN"
Returns the full company object. Use ?include=teams,agents to embed nested objects in the response: 
curl -s "http://localhost:3100/v1/companies/cmp_a1b2c3?include=teams,agents" \
  -H "Authorization: Bearer $CA_API_TOKEN"
Available includes: teams, agents, workflows, budgets.

​
Update a company

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3 \
  -X PATCH \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Accounting firm in Sandton. Updated April 2026.",
    "budget": { "usd": 750 }
  }'
You can PATCH any field except id, slug, createdAt, and teamCount/agentCount. To rename a company’s slug, you have to archive it and create a new one; slugs are permanent.

​
Archive and restore

Archive is a soft delete. The company is hidden from default lists, its agents stop accepting new tasks, and its runtime services are torn down. Archived companies keep their data for at least 30 days. 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/archive \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN"
Restore reverses the archive within the grace window: 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/restore \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN"

​
Hard delete

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3 \
  -X DELETE \
  -H "Authorization: Bearer $CA_API_TOKEN"
Requires the admin scope. Hard delete removes the company and all its data from the database. The workspaces directory on disk is also cleaned up. This is irreversible.

​
Webhooks

Companies emit these events:
EventWhen
company.createdA company is created
company.updatedAny PATCH
company.archivedCompany is archived
company.restoredCompany is restored
company.deletedCompany is hard deleted
company.budget.breachAny breach on the company-level budget

​
Next

  • Agents — next resource after creating a company
  • Goals and projects — planning layer for work inside a company
  • Costs — where the company-level cost roll-ups live