56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
---
|
|
read_when:
|
|
- changing REST endpoints, websocket behavior, SDK methods, or OpenAPI
|
|
- adding integrations or bots
|
|
---
|
|
|
|
# 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](../features/auth.md)):
|
|
|
|
1. `Authorization: Bearer <token>` (session token, magic-link result).
|
|
2. `cc_session` cookie.
|
|
3. `X-ClickClack-User: usr_...` header (local/dev impersonation for tests).
|
|
4. Dev fallback to the first user in the DB (disable in production via
|
|
`--dev-bootstrap=false`).
|
|
|
|
## Endpoint groups
|
|
|
|
| Group | Endpoints | Doc |
|
|
|---------------|-----------|-----|
|
|
| Auth | `/api/auth/magic/{request,consume}`, `/api/auth/github/{start,callback}` | [auth](../features/auth.md) |
|
|
| Profile | `/api/me` | [profiles](../features/profiles.md) |
|
|
| Workspaces | `/api/workspaces`, `/api/workspaces/{id}` | [workspaces](../features/workspaces.md) |
|
|
| Channels | `/api/workspaces/{id}/channels`, `/api/channels/{id}` | [workspaces](../features/workspaces.md) |
|
|
| Messages | `/api/channels/{id}/messages`, `/api/messages/{id}` | [messages](../features/messages.md) |
|
|
| Threads | `/api/messages/{id}/thread`, `/api/messages/{id}/thread/replies` | [threads](../features/threads.md) |
|
|
| Replies | `quoted_message_id` on any message-create endpoint | [replies](../features/replies.md) |
|
|
| Reactions | `/api/messages/{id}/reactions` | [reactions](../features/reactions.md) |
|
|
| Realtime | `/api/realtime/{ws,events,ephemeral}` | [realtime](../features/realtime.md) |
|
|
| Search | `/api/search` | [search](../features/search.md) |
|
|
| Uploads | `/api/uploads`, `/api/messages/{id}/attachments` | [uploads](../features/uploads.md) |
|
|
| DMs | `/api/dms`, `/api/dms/{id}/messages` | [dms](../features/dms.md) |
|
|
| Integrations | `/api/hooks/mattermost/{channel}`, `/api/hooks/slash/{channel}` | [integrations](../features/integrations.md) |
|
|
|
|
## Conventions
|
|
|
|
- All payloads are JSON unless explicitly multipart (uploads) or
|
|
form-encoded (slash commands).
|
|
- Mutating endpoints return both the affected resource and the durable event
|
|
emitted (`{message, event}`), so clients can reconcile optimistically.
|
|
- Pagination on listings uses cursor-style sequence numbers (`after_seq` for
|
|
channel/DM messages, `after_cursor` for events).
|
|
- Errors come back as `{ "error": "<message>" }` with an HTTP status code.
|
|
|
|
## SDK
|
|
|
|
TypeScript consumers should use `@clickclack/sdk-ts`. It depends on neither
|
|
Svelte nor any HTTP framework. See [../sdk.md](../sdk.md).
|