Elaras/

REST API

A server-side REST API for managing every Elaras Ask resource programmatically — agents, personalities, skills, knowledge, flows, scenarios, webhooks, and sessions. Authenticated with a secret key and intended for backend use only.

Authentication

Create a key under Developer > API Keys in the dashboard. Keys are team-scoped and grant access to all resources in your team.

Pass the key as a Bearer token on every request:

Authorization: Bearer sk_live_your_key_here

Never use secret keys in client-side code.

Base URL

https://ask-api.elaras.ai/api/developer/v1

Rate limits

60 requests per minute per team. Exceeding the limit returns a 429 response.


Sessions

Read conversations, create new sessions, and send messages programmatically.

MethodPathDescription
GET/sessionsList all sessions for your team
POST/sessionsCreate a new session (optionally with external identity passthroughs)
GET/sessions/{session_id}Get a session with full message history
POST/sessions/{session_id}/messagesSend a message (queued, response via WebSocket)
POST/sessions/{session_id}/streamSend a message and wait for the response over SSE

Create a session

Idempotent on session_token — passing the same token twice returns the existing session.

POST /sessions
{
  "chatbot_id": 123,
  "session_token": "optional-uuid-you-generated",
  "external_user_id": "u_42",
  "external_profile_id": "tenant:acme",
  "external_org_id": "org_xyz"
}

The three external_* fields are identity passthroughs — a bounded way to attach context for a session that gets forwarded to your webhook skill payloads under session.external. See Webhooks for the exact shape.

  • external_user_id — your end-user ID. HMAC-verifiable via identity_token when the chatbot has strict identity enabled.
  • external_profile_id / external_org_id — plain structured context (regex-restricted to [A-Za-z0-9_\-:./]+, max 255 chars each). Not identity, not HMAC-verified; just forwarded.

Response (201 for a newly-created session, 200 for an idempotent repeat):

{
  "data": {
    "id": "f7a3...",
    "chatbot_id": 123,
    "external_user_id": "u_42",
    "external_profile_id": "tenant:acme",
    "external_org_id": "org_xyz",
    "started_at": "2026-10-11T13:15:00Z",
    "message_count": 0
  }
}

Send a message

POST /sessions/{session_id}/messages
{ "message": "Your order has shipped!" }

The message is queued and processed by a worker. The AI's response is delivered over the session's Reverb WebSocket channel — see Real-time updates below. If the visitor has the widget open they receive it in real time. To receive the response in the same HTTP connection without WebSocket or polling, use /stream instead.

Stream a response

POST /sessions/{session_id}/stream
{ "message": "Your order has shipped!" }

Returns a text/event-stream response. The connection stays open while the AI generates its reply, emitting delta events for each token chunk as they arrive, then a final done event when the response is complete.

data: {"type":"delta","content":"Your subscription"}

data: {"type":"delta","content":" is active."}

data: {"type":"done","content":"Your subscription is active.","message_id":42,"credits_used":1,"blocks":[],"retrieved_sources":[]}

data: {"type":"skill_result","skill":"check_subscription","result":{},"blocks":[]}

data: {"type":"error","code":"stream_failed","message":"..."}
EventFieldsDescription
deltacontent: stringToken chunk — concatenate all chunks to assemble the full response
donecontent: string, message_id: number, credits_used: number, blocks: Block[], retrieved_sources: Source[]AI response complete — content is the full assembled text, blocks contains any structured UI blocks returned by skills
skill_resultskill: string, result: object, blocks: Block[]Emitted for fire-and-forget skills only — the skill's raw result and any blocks it returned, before the LLM generates a reply
errorcode: string, message: stringProcessing failed

When to use /stream: when you control the backend and want the full response in a single HTTP connection — ideal for white-label integrations where your backend proxies the stream to your own frontend. Token deltas arrive as the AI types, so you can forward them in real time without a separate WebSocket setup.

When to use /messages + WebSocket: when your frontend connects to the real-time channel directly for typing indicators and live token streaming without going through your backend.


Real-time updates

Elaras exposes a WebSocket channel per session so your frontend can receive token-by-token streaming and typing indicators as they happen — no polling required.

Channel

chat.{session_id}

No authentication is required to subscribe. The session ID acts as a capability token: only clients that know the UUID can access the channel.

Events

EventPayloadDescription
chat.token{ content: string }Next chunk of the AI's reply
chat.done{ message_id, content, blocks, enrichment, retrieved_sources, current_state, credits_used }AI finished responding — blocks contains structured UI blocks, retrieved_sources contains knowledge citations
chat.error{ code: string, message: string }Processing failed
chat.typing{}AI has started processing
skill.calling{ name: string }A skill is being invoked
skill_result{ skill: string, result: object, blocks: Block[] }Fired for fire-and-forget skills only — the result arrives before the AI reply instead of inside done

Connection details

Your WebSocket host, port, and app key are available in the Elaras dashboard under Settings → Developer → Real-time.


Agents

Full CRUD for agents.

MethodPathDescription
GET/chatbotsList all agents
POST/chatbotsCreate an agent
GET/chatbots/{id}Get an agent
PUT/chatbots/{id}Update an agent
DELETE/chatbots/{id}Delete an agent
POST/chatbots/{id}/assign-modelAssign a personality to an agent

Create an agent

{
  "name": "Support Bot",
  "greeting_message": "Hi! How can I help?",
  "fallback_message": "I'm not sure about that — let me connect you with someone."
}
FieldRequiredDescription
nameYesDisplay name, max 100 chars
greeting_messageNoShown when the widget opens
fallback_messageNoUsed when the agent cannot help
memory_enabledNoEnable per-visitor memory
collect_leadsNoEnable lead capture

Assign a personality

{ "bot_model_version_id": 42 }

Skills

Skills live at the workspace level. Manage them directly, or attach them to specific agents.

MethodPathDescription
GET/skillsList workspace skills
POST/skillsCreate a skill
PUT/skills/{id}Update a skill
DELETE/skills/{id}Delete a skill
POST/skills/{id}/testTest a skill

Attaching skills to an agent

Skills are attached at the personality version level, not the agent level. Pass skill_ids inside snapshot when creating or updating a draft version:

PUT /models/{model_uuid}/versions/{version_number}
{
  "snapshot": {
    "skill_ids": [123, 456]
  }
}

skill_ids are the integer IDs returned by GET /skills (the id field, not uuid). Skills take effect when the version is published and assigned to an agent.

Test a skill

POST /skills/{id}/test
{
  "params": { "query": "Who do we play next?" },
  "session": {
    "external_user_id": "u_42",
    "external_org_id": "org_xyz"
  }
}

session is optional. Omit it to test without identity context.

Elaras forwards to your skill endpoint as:

{
  "params": { "query": "Who do we play next?" },
  "session": { "external": { "user_id": "u_42", "org_id": "org_xyz" } }
}

Create a skill

{
  "name": "get_order_status",
  "description": "Look up the status of a customer order. Call when the user asks about their order, delivery, or tracking.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "description": "The order ID to look up" }
    },
    "required": ["order_id"]
  },
  "endpoint_url": "https://your-api.com/skills/order-status",
  "api_key": "your_signing_secret"
}
FieldRequiredDescription
nameYesLowercase snake_case, max 64 chars
descriptionYesPlain English — the AI reads this to decide when to call the skill
parametersNoJSON Schema object describing the parameters the AI should extract
output_schemaNoJSON Schema of what your endpoint returns — helps the AI reason about the response
endpoint_urlYesPublicly reachable URL Elaras will POST to
api_keyNoSent as Authorization: Bearer to your endpoint and used to sign requests

Knowledge

MethodPathDescription
GET/knowledgeList knowledge documents
POST/knowledge/urlAdd a URL
POST/knowledge/crawlCrawl a site
POST/knowledge/qaAdd a Q&A pair
GET/knowledge/{id}Get a document
PATCH/knowledge/{id}Rename a document or update Q&A content
DELETE/knowledge/{id}Delete a document
POST/knowledge/{id}/resyncRe-fetch and re-index a document
POST/knowledge/{id}/cloneClone a document
GET/knowledge/{id}/chunksList indexed chunks for a document

Add a URL

{ "url": "https://yoursite.com/faq", "name": "FAQ" }

Crawl a site

{ "url": "https://yoursite.com", "name": "Main site", "page_limit": 50 }

Add a Q&A pair

{ "question": "What are your opening hours?", "answer": "Monday to Friday, 9am–6pm." }

Update a document

Rename any document type, or replace the content of a Q&A document. All fields are optional — only include what you want to change.

{ "name": "Opening hours (updated)" }

To update Q&A content, provide both questions and answer together:

{
  "questions": ["What are your opening hours?", "When are you open?"],
  "answer": "Monday to Friday, 9am–6pm. Saturday 10am–4pm."
}
FieldApplies toDescription
nameAll typesRename the document, max 200 chars
questionsQ&A onlyArray of question variants (1–10), max 1000 chars each
answerQ&A onlyThe answer text, max 5000 chars

questions and answer must always be sent together. Sending one without the other returns 422.

Updating Q&A content triggers a re-index automatically — the document status returns to pending until indexing completes.

Note: If the document is referenced by a published personality version, editing its content returns 403. Clone the document first, edit the copy, then publish a new personality version pointing to the clone.


Flows

MethodPathDescription
GET/flowsList flows
POST/flowsCreate a flow
PUT/flows/{id}Update a flow
DELETE/flows/{id}Delete a flow
POST/flows/generateGenerate a flow from a description

Attaching flows to an agent

Flows are attached at the personality version level, not the agent level. Pass flow_attachments inside snapshot when creating or updating a draft version:

PUT /models/{model_uuid}/versions/{version_number}
{
  "snapshot": {
    "flow_attachments": [{ "id": 12, "trigger_phrase": "book appointment", "enabled": true }]
  }
}

Flows take effect when the version is published and assigned to an agent.

Generate a flow

{ "description": "Collect name, email, and support request, then confirm a callback time." }

Personalities

Personalities are the versioned model configurations assigned to agents.

MethodPathDescription
GET/modelsList personalities
POST/modelsCreate a personality
GET/models/{id}Get a personality
PUT/models/{id}Update a personality
DELETE/models/{id}Delete a personality
GET/models/{id}/versionsList versions
POST/models/{id}/versionsCreate a draft version
PUT/models/{id}/versions/{version_id}Update a draft version
POST/models/{id}/versions/{version_id}/publishPublish a version
POST/models/{id}/versions/{version_id}/cloneClone a version
DELETE/models/{id}/versions/{version_id}Delete a draft version

Create a personality

{ "name": "Support v2", "description": "Friendlier tone for the new support flow" }

Scenarios

Test cases for validating personality versions. Scoped to a personality.

MethodPathDescription
GET/models/{id}/scenariosList scenarios
POST/models/{id}/scenariosCreate a scenario
POST/models/{id}/scenarios/draftDraft scenarios with AI
GET/models/{id}/scenarios/{scenario_id}Get a scenario
PUT/models/{id}/scenarios/{scenario_id}Update a scenario
DELETE/models/{id}/scenarios/{scenario_id}Delete a scenario
GET/models/{id}/scenario-runsList test runs
POST/models/{id}/scenario-runsStart a test run
GET/models/{id}/scenario-runs/compareCompare two runs
GET/models/{id}/scenario-runs/{run_id}Get run results
POST/models/{id}/scenario-runs/{run_id}/cancelCancel a run

Create a scenario

{
  "name": "Refund happy path",
  "initial_message": "I need a refund.",
  "turns": [
    {
      "bot_criteria": {
        "required_facts": ["mentions the refund policy", "offers next steps"],
        "prohibited": ["mention competitor names"],
        "expected_action": "get_order_status"
      },
      "user_reply": "That works for me."
    },
    {
      "bot_criteria": {
        "required_facts": ["confirms the refund has been processed"]
      },
      "user_reply": null
    }
  ],
  "session_context": {
    "external_user_id": "u_42",
    "external_org_id": "org_xyz"
  }
}
FieldRequiredDescription
nameYesShort human-readable title, max 200 chars
initial_messageYesThe first user message that starts the scenario
categoryNoGrouping tag, e.g. happy_path, edge_case, regression. Defaults to CUSTOM
intentNoOne sentence describing what this scenario is designed to test
turnsYesArray of turn objects — see below
session_contextNoPre-seeds the session with external identity fields before the scenario runs
overall_criteriaNoEnd-of-scenario checks, e.g. {"max_turns": 6}

Turns

Each turn has two fields:

FieldDescription
bot_criteriaChecks applied to the bot's response for this turn — see below
user_replyThe user's next message. null on the final turn

bot_criteria

All fields are optional. Pass a flat string array as a shorthand — it is automatically promoted to { "required_facts": [...] }.

FieldTypeDescription
required_factsstring[]Things the bot must say — scored by an AI judge
prohibitedstring[]Things the bot must not say — scored by an AI judge
expected_actionstringSkill name that must be called this turn (deterministic)
entered_flowintegerFlow ID the bot must have entered this turn (deterministic)
capturedobjectFlow-captured variables to assert — values are regexes, e.g. {"email": ".*@.*\\.com"}

Deterministic checks (expected_action, entered_flow, captured) fail the turn immediately on mismatch. AI-judged checks (required_facts, prohibited) are scored by an LLM and contribute to the weighted score.

session_context

Pre-seeds the session with external identity fields before the scenario runs. Useful when your skills need identity to resolve user-specific data.

FieldTypeDescription
external_user_idstringYour end-user ID
external_profile_idstringExternal profile reference
external_org_idstringExternal organisation reference

Preview

Send a message to an agent and get the full response back in a single JSON call — no live user needed. Useful for verifying skill behaviour, flow logic, and session-gated access before going live.

MethodPathDescription
POST/chatbots/{id}/previewSend a preview message
DELETE/chatbots/{id}/preview/{session_token}Clear a preview session

Request body:

{
  "message": "Check my subscription status.",
  "session_token": "optional-uuid-to-continue-a-session",
  "session": {
    "external_user_id": "user-123",
    "external_org_id": "org-456"
  }
}

session_token — omit to start a fresh session. The generated token is returned in the response so you can send follow-up messages in the same conversation.

session — optional. Pass external_user_id and/or external_org_id to seed the session with your user's identity before the message is sent. Your skill endpoints receive these values in session.external so you can test access control without a real user session.

Response:

{
  "session_token": "uuid",
  "response": "Your subscription is active on the Pro plan.",
  "blocks": [],
  "enrichment": null,
  "trace": {
    "skills_called": [{ "name": "check_subscription", "latency_ms": 143 }],
    "flow_transitions": []
  }
}

blocks — structured UI components returned by skill calls during this turn. Identical to the blocks field in /stream done events and chat.done WebSocket events. Use this to render cards, buttons, or charts alongside the text response. enrichment is a legacy alias — prefer blocks.


Webhooks

MethodPathDescription
GET/webhooksList webhooks
POST/webhooksCreate a webhook
PUT/webhooks/{id}Update a webhook
DELETE/webhooks/{id}Delete a webhook
GET/webhooks/{id}/deliveriesList delivery attempts
POST/webhooks/{id}/deliveries/{delivery_id}/redeliverRetry a delivery
POST/webhooks/{id}/testSend a test event
POST/webhooks/{id}/rotate-secretRotate the signing secret

Create a webhook

{
  "name": "CRM sync",
  "url": "https://your-api.com/webhooks/elaras",
  "events": ["lead.captured"]
}

See Webhooks for event payloads and signature verification.


Errors

All errors return the same shape:

{ "message": "Human-readable description." }
StatusMeaning
401Missing or invalid API key
403Valid key but insufficient scope
404Resource not found
422Validation error
429Rate limit exceeded
500Server error — retry with backoff