Developer

REST API

One HTTP endpoint, one bearer token per bot. Stream tokens back to your UI or pipe replies into automations — same agent, same memory, same citations.

Authentication

Get a token from API tokens. Pass it as a Bearer header on every request.

Authorization: Bearer amk_live_abc123…

The widget itself doesn't need a token — it's authenticated by the bot ID it ships with. Every other caller does.

POST /api/chat

Send messages, get a streamed reply.

curl https://YOUR-DOMAIN/api/chat \
  -H "Authorization: Bearer amk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "00000000-0000-0000-0000-000000000000",
    "id": "session-123",
    "messages": [
      { "role": "user", "content": "How do refunds work?" }
    ]
  }'

Body fields

botId — required UUID. Must match the bot the token was issued for.
messages — required array. { role: "user" | "assistant", content: string }.
id — optional session id. Pass the same value across turns to chain a conversation. We hash non-UUID ids to a stable conversation key automatically.
visitorId — optional opaque visitor identifier (your own user id, anonymized).

Response

A streamed data-streamin the Vercel AI SDK's UIMessage format. Each event is JSON-prefixed text: text deltas, tool calls, tool results, and a final finish. Easiest to consume via useChat from ai/react.

POST /api/messages/feedback

Record a thumbs-up / thumbs-down on any logged assistant message. Ratings power the Helpful rate stat and surface failing answers in the dashboard.

curl https://YOUR-DOMAIN/api/messages/feedback \
  -H "Authorization: Bearer amk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "botId": "00000000-0000-0000-0000-000000000000",
    "messageId": "11111111-1111-1111-1111-111111111111",
    "feedback": 1
  }'

feedback — 1 = helpful, -1 = not helpful, 0 = clear.

Rate limits

Requests are rate-limited per IP plus per workspace quota. When a workspace exceeds its plan's reply allowance, the API returns 403 Quota exceeded until the next cycle or an upgrade.

HTTP 429 includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Webhooks (coming soon)

Subscribe to conversation.escalated, lead.captured, and quota.warning so you can route events to your CRM / Slack / PagerDuty without polling.

API tokens →