Public API

These are the endpoints the embedded widget itself calls. They are public — no user login — and authenticated by your site key. You can use them directly to build a custom chat UI.

Authentication

Send your site key as a header. Requests are also checked against your domain allowlist, so a leaked key cannot be used from another site.

X-Site-Key: your-site-key

Get widget config

GET /public/widget-config

Returns appearance settings. Used by the widget on load.

{
  "widgetPosition": "bottom_right",
  "widgetPrimaryColor": "#14B8A6",
  "widgetFontFamily": "inherit",
  "widgetLogoUrl": null,
  "widgetAssistantName": "Minaya",
  "widgetWelcomeMessage": "Hi, I am Minaya your AI assistant...",
  "widgetHeaderTextColor": "#FFFFFF",
  "widgetBotBubbleColor": "#F1F1F3",
  "widgetBotTextColor": "#18181B",
  "widgetUserTextColor": "#FFFFFF",
  "widgetOpenByDefault": false,
  "widgetCustomCss": null
}

widgetAssistantName is resolved server-side — it is always a string, never null.

Send a message

POST /public/chat

{
  "message": "Do you ship to Canada?",
  "sessionId": "optional-existing-session",
  "visitorIdentifier": "optional-stable-visitor-id",
  "stream": false,
  "origin": "https://example.com",
  "country": "CA"
}

Omit sessionId to start a conversation; the response returns one to reuse for follow-ups.

{ "sessionId": "…", "reply": "Yes — 3 to 5 business days…", "messageId": "…" }

With stream: true the reply arrives as server-sent events, each carrying a content delta and a final done event.

Get history

GET /public/chat/history/:sessionId

Returns the messages in a session, scoped to your business so one site's widget can never read another's conversations. Used to restore a conversation when a visitor reopens the widget.

Rate a message

POST /public/chat/feedback

{ "messageId": "…", "feedback": "up" }

Accepts up or down, and only for assistant messages. Ratings appear in your dashboard analytics.

Analytics events

POST /public/track-click
POST /public/track-page-view

Fired when the widget is opened and when a page loads. Both accept an optional sessionId, visitorIdentifier, origin, and country.

Rate limits and caps

Chat requests are rate-limited per site key.
50 messages per session.
2,000 characters per message.
Free-tier businesses have a daily message cap.

Exceeding a limit returns a normal reply explaining the situation rather than an error, so a custom UI can display it like any other message.

Dashboard API

Managing knowledge sources, appearance, and MCP servers uses authenticated endpoints under the same host, documented in the OpenAPI spec at /api/docs on your deployment.

PreviousMCP integration NextSecurity