API reference

The /api/v1/application/* surface - what your API key can call, grouped the way you build against it.

Sections are in integration order: sign the user in, find out what they may do, find out whether their workspace may be here at all, then the optional capabilities.

Before you start

Use the SDK if you can. npm install @cosmoops/connect-sdk wraps every endpoint here, typed, with retries and Idempotency-Key handling built in. These pages are the contract underneath it - reach for them when you are on a language the SDK does not cover, or when you need to know exactly what a call sends.

Auth. Authorization: Bearer <api key> everywhere, except /sso/*, which takes client_id/client_secret (RFC 6749). There is no separate client secret - the OAuth2 client_secret is an API key's plaintext.

Scopes. Every endpoint states the scope it needs. A key carries only the scopes it was created with, and can be re-scoped later without rotating it - see Authorization for how those relate to the permissions your members hold, which is a different thing entirely.

Errors. One envelope outside /sso/*: { error: { code, message } }. Branch on code; message is for humans. A 429 carries Retry-After in seconds.

Every credential failure is HTTP 403. key_revoked / key_expired mean this key is dead - reissue it; no retry or scope change will help. forbidden covers everything else (unknown key, missing scope, IP not allowlisted) and is deliberately indistinguishable between those causes.

Sections

• Identity (6 endpoints) — "Login with Connect" - the OAuth2 handshake, plus the session lifecycle that outlives it.
• Access (2 endpoints) — What a signed-in member may do on this application: their resolved permissions, and the role catalog those come from.
• Entitlements (5 endpoints) — Whether a workspace may use this application at all, and on what plan - the two checks worth making on every request.
• Billing (7 endpoints) — The plan catalog this application sells, and metering usage back against a subscriber's add-on balance.
• Drive (6 endpoints) — Upload a file into a workspace's Drive and read back signed URLs for it.
• AI (13 endpoints) — RAG chat and structured extraction against a workspace's data, and company enrichment from a domain.
• WhatsApp (2 endpoints) — Send your application's own Meta-approved WhatsApp templates to a workspace's customers, through Connect's WhatsApp sender - and check whether a template is live before offering it.
• Email (1 endpoint) — Send your application's own email - a support reply, a sign-in code - on behalf of a subscribing workspace, through Connect's sending identity and its bounce and complaint suppression list.
• Push notifications (1 endpoint) — Put a notification on a member's lock screen. Connect holds the VAPID keys, the devices and the member's own preferences - your application supplies a title, a body and a path.
• Task queues (1 endpoint) — Background jobs delivered back to your own endpoint by Cloud Tasks, at a rate you declare - for work too long for one request, like sending a campaign page by page.
• Workspaces (10 endpoints) — Which workspaces the signed-in user belongs to, switching between them, and who else is on the team.
• Data (9 endpoints) — Your application's own document store - a dedicated Firestore database, partitioned per workspace, with Connect doing the authorization and the audit.
• KV (4 endpoints) — Your application's key/value store - small values addressed by namespace and key, per workspace.
• OTP (2 endpoints) — WhatsApp/SMS phone verification, send and verify.
• Logs (1 endpoint) — Push feature events into Connect's audit log, filterable to this application.
• Analytics (2 endpoints) — Emit your own product events, and read back aggregated usage, API volume and revenue for this application.
• Integrations (5 endpoints) — Composio-hosted third-party connections (Google Calendar, Slack, ...) a workspace has connected, and executing actions against them.
• Channels (10 endpoints) — The phone numbers assigned to your application, and where each one sends its inbound calls.
• Calls (12 endpoints) — What actually happened on your channels: outcome, duration, transcript, tool calls and post-call extraction.
• Contacts (3 endpoints) — Who a workspace knows how to reach - the telephony identity an inbound call resolves to.
• Scheduling (13 endpoints) — A subscribing workspace's own calendar: what is bookable, what is free, and booking it.
• Visitor assistant (8 endpoints) — The public chat bubble on your own marketing site: a stranger asks about your product, books a call, or signs up - with no account and no session anywhere in it.
• Platform (1 endpoint) — Connect's own legal identity and DPDP grievance channel - the block your privacy notice and consent capture have to name.