API reference

HTTP-first. JSON in, JSON out.

Every dashboard action is also an endpoint. Auth via the bearer token from your Account → API keys page (coming soon, for now use Supabase auth cookies).

Auth

Most endpoints are agent-scoped: they read the logged-in agent\'s user_id and resolve org_id from the agents table. Browser-based callers use the Supabase auth cookie (no manual header needed). Server-to-server callers should hit the upcoming Bearer ${token} path.

Widget endpoints (/api/widget/*, /api/chat) are intentionally public-CORS so the embedded widget can reach them from any host. They scope all data by org_id + visitor_id.

Sessions

POST/api/sessions

Create or resume a chat session for a visitor.

GET/api/sessions?sessionId=…

Read messages + session meta + agent typing state.

POST/api/sessions/end

Close a session.

Messages + AI

POST/api/chat

Send a customer message and stream the AI reply.

POST/api/messages

Agent posts a reply into a session.

Visitor + cart

POST/api/visitor-ping

Heartbeat to keep widget_visitors alive.

GET/api/widget/cart?orgId=…

Rehydrate the visitor's Shopify cart card.

POST/api/widget/cart/line

Mutate one line in the cart (qty change or remove).

Broadcasts + triggers

POST/api/sessions/cold-chat/broadcast

Send one message to all live visitors right now.

GET/api/scheduled-broadcasts

List scheduled broadcasts.

POST/api/scheduled-broadcasts

Create one.

PATCH/api/scheduled-broadcasts/:id

Update one.

DELETE/api/scheduled-broadcasts/:id

Delete one.

POST/api/scheduled-broadcasts/:id

Run now (manual trigger).

Canned shortcuts

GET/api/canned-responses

List the org's saved shortcuts.

POST/api/canned-responses

Create a shortcut.

PATCH/api/canned-responses/:id

Edit a shortcut.

DELETE/api/canned-responses/:id

Delete a shortcut.

Widget config

GET/api/widget-config?propertyId=…

Public, returns the customer-facing widget config (color, palette, behavior toggles, etc.).

Rate limits

Free plan: 60 requests/minute per org. Pro: 600/min. Enterprise: custom. Limits are per-endpoint and reset every 60s. Hitting the limit returns 429 Too Many Requests with a Retry-After header.