Public Widget API

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 } }.