Developer

REST API

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

Authentication

Every public agent endpoint requires a Bearer token. Server integrations use a long-lived API token from API tokens. The embeddable widget uses a short-lived session token issued automatically — you never put API tokens in browser JavaScript.

Authorization: Bearer amk_live_abc123…

botId alone is not enough — requests without a valid bearer token return 401. The token must match the botId in the request body.

Widget session tokens

When the widget loads on an allowed domain, it calls POST /api/widget/session and receives an amk_wgt_token (~1 hour TTL). That token is attached to chat, sync, history, presence, and feedback requests automatically. Allowed domains are your agent's website URL, Agentmatica share / playground pages, and any extra domains listed under Deploy.

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 agent 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 API token (server integrations) or per visitor IP (embed widget). Workspace reply quotas still apply separately — when a workspace exceeds its plan's reply allowance, the API returns 403 Quota exceeded.

API token limits (per minute, per token):

• POST /api/chat — 60 requests
• GET /api/conversations/sync — 60 requests (poll at most once per second; prefer once every 2 seconds)
• History, end, feedback — 90 requests combined
• Presence heartbeats — 120 requests

HTTP 429 includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Back off and retry after the reset timestamp.

Webhooks (coming soon)

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