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 → Security.

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-stream in 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

Session-token issuance itself (POST /api/widget/session) is limited to 60 requests per minute per visitor IP.

Widget session tokens are stricter: 40 chat requests, 30 sync requests, 60 history/end/feedback requests, and 120 presence heartbeats per minute per session.

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

Webhooks

Subscribe to lead.captured and conversation.escalated to route events to your CRM, Slack, or PagerDuty without polling. Deliveries are HMAC-signed and configured per agent — see Custom webhook.

MCP server

The same bearer token also works against POST /api/mcp, a Model Context Protocol endpoint that exposes docs search, plan comparison, and agent lookups to Claude, Cursor, or your own agent. See Agentmatica MCP server.