REST API

Use the REST API to talk to your assistants from your own backend. This is the same runtime used by the embeddable widget, but here you call it server to server using a separate API key (not exposed on the frontend).

Authentication (API key)

For server‑to‑server messaging we assume a dedicated API key that you keep secret on your backend (separate from the widget’s publishable key).

Send the API key in one of these headers from your server:

X-API-Key: YOUR_API_KEY

or

Authorization: Bearer YOUR_API_KEY

The API key is scoped to a workspace. You must also provide workspace_id and bot_id in the request body.

Runtime messages endpoint (server‑to‑server)

POST /api/v1/runtime/messages/api

Send a user message to an assistant and receive a response.

Request body:

{
  "workspace_id": "workspace_123",
  "bot_id": "bot_456",
  "session_id": "optional-session-uuid",
  "user_message": "Hello! I have a question about pricing.",
  "context": {
    "channel": "api"
  },
  "trace_id": "optional-trace-id",
  "persona": "Optional request-level persona override",
  "history": [
    {
      "role": "user",
      "message": "Previous message",
      "timestamp": "2026-03-15T10:00:00Z"
    }
  ]
}

Response body:

{
  "bot_message": "Here is the answer to your question...",
  "citations": [
    {
      "source_id": "content-source-id",
      "excerpt": "Relevant snippet from your document...",
      "score": 0.94,
      "metadata": {
        "title": "Pricing FAQ",
        "page": 3
      }
    }
  ],
  "confidence": 0.92,
  "latency_ms": 850,
  "tools_invoked": [
    {
      "tool_name": "Retrieval",
      "status": "success",
      "duration_ms": 420
    }
  ],
  "fallback_triggered": false,
  "session_id": "returned-or-reused-session-id"
}

You can reuse the session_id across messages to maintain conversation context.

Server‑to‑server examples

Below is a minimal example for POST /api/v1/runtime/messages/api. Choose your language and copy the snippet.

These examples are designed to be copy‑pasted into your backend and adapted with your own API base URL, workspace_id, bot_id, and environment variables for the API key.