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