API Reference

Design philosophy

The API surface is deliberately small: a chat-style endpoint that takes your messages and returns an answer grounded in your workspace's documents.

You don't need to worry about tokenisation, chunking or embeddings – that's all handled server-side. You simply:

1. Specify which bot/workspace you're talking to.
2. Send the conversation history.
3. Receive an answer plus metadata (tokens, citations, etc.).

Authentication

API keys are managed from the admin console under Settings → API keys. Each key is scoped to a workspace and inherits its plan limits and quotas.

For server-side usage, send your API key in an Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

Chat endpoint

The core endpoint accepts a list of messages and returns a single answer object. Exact URL and fields may evolve, but the shape follows this pattern:

POST /api/public/chat

{
  "bot_id": "bot_123",
  "messages": [
    { "role": "user", "content": "What are your support hours?" }
  ]
}

A typical response:

{
  "ok": true,
  "answer": "Our support hours are 9am–5pm Monday to Friday (UK time).",
  "citations": [
    {
      "document_id": "doc_abc",
      "title": "Support policy",
      "snippet": "We offer support Monday–Friday, 9am–5pm UK time..."
    }
  ],
  "usage": {
    "prompt_tokens": 1200,
    "completion_tokens": 80,
    "total_tokens": 1280
  }
}

You can safely cache answers in your own system if you want to avoid repeated calls for the same question.

Rate limits & quotas

Each workspace inherits limits from its current plan (for example, monthly tokens and maximum documents). API requests count against the same pool as widget and admin traffic.

If a request would exceed your quota, the API returns an error with a clear message so you can handle it gracefully in your own app.

When to use the API vs the widget

• Use the widget when you want quick, no-code chat on your marketing site, portal, or help centre.
• Use the API when you want to:
  • Inject answers into an existing product UI.
  • Enrich your own CRM or support tools.
  • Build custom flows around the bot's responses.