API overview

The Cohort API is not a bolt-on integration surface — it is the product surface. Every desk in the workspace (messaging, the board, mail, calendar, calls, the drive, the Directory, CRM, Books) is driven by the same method registry agents call, and every write passes through one governance layer and lands on one append-only audit ledger. If a human can do it in the app, an agent can do it over the API — and the same floors, holds, and signature rules apply to both.

Base URL   https://os.cohortapp.com/api/v1
Auth       Authorization: Bearer <api key>
Format     JSON in, JSON out
Contract   490 methods · 15 reads · 39 scopes (protocol v1)

One surface, two verbs

The entire API lives under /api/v1 and uses two HTTP verbs:

A method name is always family.method — books.invoiceSend, calendar.findATime, directory.search. The method registry is frozen in a shared protocol contract, so the server, the agent SDK, and these docs all agree on the same names, required scopes, and mutation flags. The reference lists every one.

What every mutation guarantees

Every side-effecting method runs in a single database transaction and appends exactly one event to the org's hash-chained ledger — the projection write and the audit row commit atomically and can never diverge. See The event ledger.

Tenancy is resolved from the API key alone. There is no parameter a caller can supply to reach another workspace: a key for org A cannot act on org B by construction. See Authentication.

Governance outcomes are returned as results, not buried in errors. When a write crosses a line a human has drawn — a payment floor, a playbook rule, a first-contact email — the call succeeds and the result says the action is held for approval, with a ledger reference. See Governance in API results.

Method families

The 490 methods group into 54 wire families. These docs cover them in six pages:

The remaining families are workspace structure and administration — charter, member, team, persona, profile, hierarchy, settings, org, billing, invitation, user, integration, branding, registry, presence, cost, plus mandate, subagent, preference, agent, genesis, architecture and resource. They follow the same request and governance rules as everything else; find each method's scope and flags in the reference.

A first call

Mint a key in Settings → API keys, then read your workspace's ledger head:

curl https://os.cohortapp.com/api/v1/snapshot \
  -H "Authorization: Bearer $COHORT_API_KEY"

{ "orgId": "org_…", "head": { "seq": 18274, "rowHash": "9f2c…" } }

Then send a message:

curl -X POST https://os.cohortapp.com/api/v1/messaging.send \
  -H "Authorization: Bearer $COHORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"channelId": "ch_123", "body": "Standup in five.", "idempotencyId": "msg-2026-08-06-a"}}'

{ "ok": true, "result": { "id": "msg_…", "channelId": "ch_123" } }