Chatbot API

Overview

The Chatbot API runs Heliuos Chat as a headless engine inside your own product. Every response is generated from your knowledge base — not the open internet. You control the data, the persona, and where the chat appears.

Base URL

https://api.heliuos.com

Authentication

All requests require an API key passed in the x-api-key header. Keys are created from the Heliuos Dashboard.

Each key carries a persona that controls how the AI responds, and a permission set — chatbot endpoints require the chat permission.

Personas

general default

Neutral, concise, precise. Falls back to this if no persona is configured on the key.

sales

Consultative tone. Asks discovery questions, handles objections naturally.

support

Patient, empathetic. Guides users step by step.

curl https://api.heliuos.com/v1/chatbot/sessions \
  -H "x-api-key: heliuos_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Sessions

Sessions store conversation history. Create a session before sending the first message, then pass the returned id as sessionId with every query. The API loads history automatically from the session on each request.

Create a session

POST /v1/chatbot/sessions

Creates a new conversation session.

Body parameters

title string optional

A label for the session. Defaults to "Chatbot session".

Returns

A session object with id, title, and createdAt. Store the id — you'll need it for every query.

curl -X POST https://api.heliuos.com/v1/chatbot/sessions \
  -H "x-api-key: heliuos_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Support thread #42"}'

{
  "success": true,
  "data": {
    "id": "sess_abc123",
    "title": "Support thread #42",
    "createdAt": "2026-06-10T08:00:00.000Z"
  }
}

List sessions

GET /v1/chatbot/sessions

Returns all sessions for the authenticated API key, newest first. Supports cursor-based pagination.

Query parameters

cursor string optional

Pagination cursor from the previous response's meta.nextCursor.

limit number optional

Maximum items per page.

curl "https://api.heliuos.com/v1/chatbot/sessions?limit=20" \
  -H "x-api-key: heliuos_xxxx"

{
  "success": true,
  "data": [
    {
      "id": "sess_abc123",
      "title": "Support thread #42",
      "createdAt": "2026-06-10T08:00:00.000Z"
    }
  ],
  "meta": {
    "nextCursor": "sess_xyz789",
    "hasMore": true
  }
}

Get session messages

GET /v1/chatbot/sessions/{sessionId}

Returns the full message history for a session. Useful for restoring a past conversation in your UI.

Path parameters

sessionId string required

The session ID from Create session.

curl "https://api.heliuos.com/v1/chatbot/sessions/sess_abc123" \
  -H "x-api-key: heliuos_xxxx"

{
  "success": true,
  "data": {
    "id": "sess_abc123",
    "messages": [
      { "role": "user", "content": "What is the refund policy?" },
      { "role": "assistant", "content": "Refunds are available within 30 days..." }
    ]
  }
}

Delete a session

DELETE /v1/chatbot/sessions/{sessionId}

Permanently deletes a session and all its messages. This action cannot be undone.

Path parameters

sessionId string required

The session ID to delete.

curl -X DELETE "https://api.heliuos.com/v1/chatbot/sessions/sess_abc123" \
  -H "x-api-key: heliuos_xxxx"

{
  "success": true,
  "data": { "message": "Session deleted" }
}

Query

Send a message and get a response from your knowledge base. Two modes: synchronous (wait for the full answer) or streaming (receive tokens in real time via SSE).

Send a message

POST /v1/chatbot/query

Returns the full answer after the pipeline completes. Best for server-side integrations that don't need real-time output.

Body parameters

message string required

The user's message.

sessionId string required

Session ID from Create session. Conversation history is loaded automatically.

format "markdown" | "text" optional

Response format. Defaults to "markdown". Use "text" for plain string output.

Returns

A response with text, optional images (when the knowledge base has relevant images), token usage, and the echoed sessionId.

curl -X POST https://api.heliuos.com/v1/chatbot/query \
  -H "x-api-key: heliuos_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the return policy?",
    "sessionId": "sess_abc123"
  }'

{
  "success": true,
  "data": {
    "text": "Returns are accepted within 30 days of purchase...",
    "images": [
      {
        "url": "https://cdn.heliuos.com/img/return-flow.png",
        "alt": "Return process diagram"
      }
    ],
    "usage": {
      "promptTokens": 512,
      "completionTokens": 128,
      "totalTokens": 640
    },
    "sessionId": "sess_abc123"
  }
}

Stream a response

POST /v1/chatbot/query/stream

Same body as Send a message. Responds as a Server-Sent Events stream — tokens arrive in real time as the model generates them.

Body parameters

message string required

The user's message.

sessionId string required

Session ID. History is loaded automatically.

format "markdown" | "text" optional

Response format. Defaults to "markdown".

SSE event sequence

event: status

Pipeline started. Data: {"status":"generating"}

data: (no event name)

Each text chunk. Data: {"type":"chunk","content":"..."}

event: metadata

Stream complete. Data: {"model":"claude-...","images":0}

event: done

Connection closing. Data: [DONE]

event: error

Pipeline failure. Data: {"message":"..."}

curl -X POST https://api.heliuos.com/v1/chatbot/query/stream \
  -H "x-api-key: heliuos_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Summarize our Q1 report",
    "sessionId": "sess_abc123"
  }'

event: status
data: {"status":"generating"}

data: {"type":"chunk","content":"Q1 revenue reached "}

data: {"type":"chunk","content":"$4.2M, up 18% year-over-year."}

event: metadata
data: {"model":"claude-sonnet-4-6","images":0}

event: done
data: [DONE]

const res = await fetch(
  'https://api.heliuos.com/v1/chatbot/query/stream',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'heliuos_xxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message, sessionId }),
  }
);

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop() ?? '';
  for (const line of lines) {
    if (!line.startsWith('data:')) continue;
    const raw = line.slice(5).trim();
    if (raw === '[DONE]') break;
    const { type, content } = JSON.parse(raw);
    if (type === 'chunk') process.stdout.write(content);
  }
}

Errors

All errors return success: false with an error object containing a machine-readable code and a human-readable message.

Error codes

Status	Code	Cause
400	BAD_REQUEST	Missing or invalid `message` / `sessionId`
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key lacks `chat` permission
500	INTERNAL_ERROR	Pipeline failure

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "message is required"
  }
}

const data = await res.json();

if (!data.success) {
  switch (data.error.code) {
    case 'UNAUTHORIZED':
      // redirect to key setup
      break;
    case 'BAD_REQUEST':
      console.error(data.error.message);
      break;
  }
}

Quick start

Create a session, send a message, and print the response — in under 20 lines.

const API_KEY = 'heliuos_your_key_here';
const BASE    = 'https://api.heliuos.com';

const h = { 'x-api-key': API_KEY, 'Content-Type': 'application/json' };

// 1. Create a session
const { data: session } = await fetch(`${BASE}/v1/chatbot/sessions`, {
  method: 'POST',
  headers: h,
  body: JSON.stringify({ title: 'My chat' }),
}).then(r => r.json());

// 2. Send a message
const { data } = await fetch(`${BASE}/v1/chatbot/query`, {
  method: 'POST',
  headers: h,
  body: JSON.stringify({
    message: 'What are your pricing plans?',
    sessionId: session.id,
  }),
}).then(r => r.json());

console.log(data.text);
// → "We offer three plans: Starter, Pro, and Enterprise..."