# Public Widget API

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

Product: Clad Widget SDK
Source: https://docs.useclad.ai/widget/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-production.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/chat` | Conversational AI assistant turn (multi‑turn RAG grounded in published articles). This is what the in‑widget AI assistant uses. |
| `POST /ai/escalate` | Mark an AI chat as escalated to a human (logs the deflection hand‑off). |
| `POST /ai/answer` | One‑shot, non‑conversational answer / article suggestions for a single question (honors `ai.mode` of `answer_first` / `suggest_articles`). |
| `GET /forms` · `GET /forms/{id}` | List/fetch ticket forms. |
| `POST /forms/{id}/submissions` | Submit a ticket form. |
| `POST /attachments` | Upload a ticket‑form image (raw bytes, `X-Filename` header; image‑only + size‑capped). Returns a short‑lived signed handle to include in a submission. |
| `POST /events` | Ingest client analytics/audit events. |
| `WS /realtime?session_token=` | Realtime gateway (WebSocket). |

**Auth:** all endpoints except `GET /config`, `POST /sessions/anonymous`, and
`POST /sessions/identify` (both create a session — `identify` uses the anonymous
session token only to merge history) 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 } }`.