API Overview
packages/protocol/openapi.yaml is the API contract source of truth. Server handlers live in apps/api/internal/httpapi; the TypeScript SDK in packages/sdk-ts is the typed client.
#Auth
The server resolves callers in this order (see ../features/auth.md):
Authorization: Bearer <token>(session token, magic-link result).cc_sessioncookie.X-ClickClack-User: usr_...header (local/dev impersonation for tests).- Dev fallback to the first user in the DB (only with
--dev-bootstrap=true).
#Endpoint groups
| Group | Endpoints | Doc |
|---|---|---|
| Auth | /api/auth/magic/{request,consume}, /api/auth/github/{start,callback} | auth |
| Profile | /api/me | profiles |
| Workspaces | /api/workspaces, /api/workspaces/{id} | workspaces |
| Moderation | /api/workspaces/{id}/moderation/members | moderation |
| Bots | /api/workspaces/{id}/bots, /api/bots/{id}/tokens, /api/bot-tokens/{id}/revoke | bots |
| App installs | /api/workspaces/{id}/app-installations, /api/app-installations/{id}/revoke | integrations |
| Slash commands | /api/workspaces/{id}/slash-commands, /api/slash-commands/{id}/revoke, /api/hooks/slash/{channel} | integrations |
| Event subscriptions | /api/workspaces/{id}/event-subscriptions, /api/event-subscriptions/{id}/{revoke,deliveries} | integrations |
| Audit log | /api/workspaces/{id}/audit-log | integrations |
| Connected accounts | /api/workspaces/{id}/connected-accounts, /api/connected-accounts/{id}/revoke | integrations |
| Topics | /api/workspaces/{id}/topics | messages |
| Channels | /api/workspaces/{id}/channels, /api/channels/{id} | workspaces |
| Messages | /api/channels/{id}/messages, /api/messages/{id} | messages |
| Threads | /api/messages/{id}/thread, /api/messages/{id}/thread/replies | threads |
| Replies | quoted_message_id on any message-create endpoint | replies |
| Reactions | /api/messages/{id}/reactions | reactions |
| Realtime | /api/realtime/{ws,events,ephemeral} | realtime |
| Search | /api/search | search |
| Uploads | /api/uploads, /api/messages/{id}/attachments | uploads |
| DMs | /api/dms, /api/dms/{id}/messages | dms |
| Integrations | /api/hooks/mattermost/{channel} | integrations |
#Conventions
- All payloads are JSON unless explicitly multipart (uploads) or
- Mutating endpoints return both the affected resource and the durable event
- Pagination on listings uses cursor-style sequence numbers (
after_seqfor - Errors come back as
{ "error": "<message>" }with an HTTP status code. - Store-level moderation restrictions surface as
403; exhausted guest post
form-encoded (slash commands).
emitted ({message, event}), so clients can reconcile optimistically.
channel/DM messages, after_cursor for events).
budgets surface as 429.
#SDK
TypeScript consumers should use @clickclack/sdk-ts. It depends on neither Svelte nor any HTTP framework. See ../sdk.md.