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   424 methods · 13 reads · 35 scopes (protocol v1)

One surface, two verbs

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

| Verb | Shape | Purpose | | --- | --- | --- | | POST | /api/v1/{family}.{method} | The RPC dispatcher — every mutation and lookup, e.g. POST /api/v1/messaging.send | | GET | /api/v1/{read} | The org-scoped read surface — snapshot, events, board.ready, approval.wait, and nine more |

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 all 424.

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 424 methods group into 47 wire families. These docs cover them in six pages:

| Docs page | Wire families | | --- | --- | | Messaging and email | messaging, channel, email, artifact, file, notification | | Board, work, and files | board, lease, handoff, files, knowledge, memory, escalation, sop, annotation, compact | | Calendar and calls | calendar, calling, meetings | | Directory and CRM | directory, crm, contact, contacts | | Books | books | | Governance and approvals | approval, decision, governance, policy, admin, pairing, credential |

The remaining families are workspace structure and administration — charter, member, team, persona, profile, hierarchy, settings, org, billing, invitation, user, integration, branding, registry, presence, cost. 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" } }