# Public Widget API

> The underlying HTTP + WebSocket Widget API for advanced and self-hosted scenarios.

Source: https://docs.useclad.ai/widget-api-reference

---

> Most integrators use the SDK and never call these directly. They are
> documented for self‑hosted/advanced scenarios and debugging. Base path:
> `https://clad-server-staging.up.railway.app/widget/v1`.

| Method & path | Purpose |
|---|---|
| `GET /config?workspace_id=&widget_id=` | Public, end‑user‑safe widget config. |
| `POST /sessions/anonymous` | Create/resume an anonymous session. |
| `POST /sessions/identify` | Upgrade to an authenticated session (send the identity JWT; the anonymous session token authorizes the merge). |
| `POST /sessions/refresh` | Extend a session. |
| `POST /sessions/shutdown` | Revoke the current session (logout). |
| `POST /sessions/realtime-token` | Mint a short‑lived token for the realtime gateway. |
| `GET /conversations` | List the session's conversations (cursor paginated). |
| `POST /conversations` | Create a conversation (`subject`, `message`, `tags`, `customFields`, `metadata`). |
| `GET /conversations/{id}` | Fetch one conversation. |
| `POST /conversations/{id}/read` | Mark read. |
| `GET /conversations/{id}/messages` | List messages (cursor paginated). |
| `POST /conversations/{id}/messages` | Send a message (`text`, `clientMessageId`). |
| `GET /articles/search?q=` | Search published articles. |
| `GET /articles/{id}` | Fetch an article. |
| `POST /ai/answer` | AI answer / article suggestions for a question. |
| `GET /forms` · `GET /forms/{id}` | List/fetch ticket forms. |
| `POST /forms/{id}/submissions` | Submit a ticket form. |
| `POST /events` | Ingest client analytics/audit events. |
| `WS /realtime?session_token=` | Realtime gateway (WebSocket). |

**Auth:** all endpoints except `GET /config` and `POST /sessions/anonymous`
require `Authorization: Bearer <session token>`. Mutating endpoints validate the
request `Origin` against the widget's allow‑list. Errors use a consistent
envelope: `{ "error": { code, message, reason?, requestId?, recoverable } }`.