API overview

Ansadesk has two HTTP surfaces. The widget API is public, token-authenticated, and CORS-open — it's what the embedded widget talks to. The app API backs the agent dashboard and uses your signed-in session. Every request and response is JSON and validated with zod; errors come back as { "error": string } with a 4xx/5xx status.

Widget API — /api/widget/*

Public, designed to run from a <script> on any origin. The widget exchanges your public widget key for a short-lived bearer token at boot and sends it as Authorization: Bearer <token> (or ?token= for the SSE stream). Tokens expire after 24h and endpoints are rate-limited per IP per minute.

POST /api/widget/boot       // key → token + branding + history
POST /api/widget/messages   // send a message (omit conversationId to start one)
GET  /api/widget/messages   // history for the visitor's own conversation
GET  /api/widget/stream     // SSE: message.created, typing, conversation.updated
POST /api/widget/typing     // broadcast visitor-typing
POST /api/widget/identify   // attach name / email / attributes
POST /api/widget/rating     // CSAT after a conversation is closed

In practice you don't call these by hand — the widget script does, and the small window.Ansadesk helper covers the common cases. See Identify users for identify() and open().

App API — /api/app/*

Backs the agent dashboard and authenticates with your Better Auth session cookie. Tenancy is enforced server-side: the workspace is resolved from your membership, never from request input, so ids belonging to another workspace return 404. Some routes require the owner role.

It covers, among other things:

• Workspaces & settings — list/create workspaces, update branding, business hours, knowledge base, autopilot and triage toggles, rotate the widget key, export data, GDPR erasure.
• Conversations — fetch a conversation with its messages and AI draft, page older messages, post replies and internal notes, change status/assignee/snooze, and stream AI drafts, summaries, and Ask AI answers.
• Realtime — a per-workspace SSE stream delivering message, conversation, and typing events (internal notes included for agents, never for the widget).
• Billing — Stripe Checkout and Customer Portal links; these return 503 unless Stripe is configured.