Developers

Last verified: 2026-09-29

Most teams only need an AI Client and the web app. This section is for developers and automation authors who want to call CompanyOS directly. There is no SDK: use curl, fetch, or any HTTP client.

Operations

Every capability is an operation with a stable ID, an input schema, the roles that can use it, and the errors it can return.

# What can I call, in this Workspace, with my role?
curl -sS "https://app.companyos.cc/api/v1/operations" \
  -H "Authorization: Bearer $COMPANYOS_TOKEN"

# Run one
curl -sS -X POST "https://app.companyos.cc/api/v1/operations/<operation_id>" \
  -H "Authorization: Bearer $COMPANYOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Treat the discovery response as the source of truth. It reflects the caller’s role, the Workspace’s connected Apps, and any grant in use. The full contract is in the OpenAPI reference.

To keep structured records, use Airtable and connect it as an App.

Errors your AI can act on

Every failure returns an AI-Actionable Error: a stable code, a plain message, whether it is recoverable, and the next step to take. An AI Client should follow next instead of guessing. The full list is in the error catalog.

Grants for unattended jobs

A job that runs without a person present authenticates with a grant: a secret that acts as one Member, in one Workspace, for exactly what the grant allows.

• An operation grant allows one operation until it expires: POST /api/v1/operation-grants with operationScope and expiresAt.
• A routine grant allows a set of operations and data for a recurring job, with a maximum cadence and an expiry: POST /api/v1/routine-grants.

Create grants while signed in as the Member the job will act as. The secret is returned once; CompanyOS stores only its hash. List grants with GET on the same path, and revoke one with DELETE /api/v1/{operation-grants|routine-grants}/{id}.

Authority is checked again on every call. A removed Member, a changed role, a disconnected App, an expired grant, or a revoked grant stops the next call. A grant never widens on its own, and never switches to another identity.

Run from your own scheduler

To run work on a schedule, start with Scheduled Procedures: CompanyOS runs them itself and emails the result, with nothing to host.

If you want your own scheduler instead, such as a Claude Cowork scheduled task or a cron job:

1. Ask your AI to list the operations the job needs, or call GET /api/v1/operations.
2. Create a routine grant scoped to only those operations and data, with a cadence and an expiry.
3. Store the secret in the scheduler’s secret settings, never in a prompt, chat, or document.
4. Have the job call those operation IDs directly, with an idempotency key per run, so a retry returns the first result instead of acting twice.
5. Run it once by hand, then once on schedule with your computer off. Only the second run proves it works unattended.

To stop it, revoke the grant. The next call fails immediately.

Claude Code and the Codex CLI can call CompanyOS too, but only while the machine running them is on. They are not hosted schedulers.