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.
| Method | Path | Description |
|---|---|---|
GET | /sessions | List all sessions for your team |
POST | /sessions | Create a new session (optionally with external identity passthroughs) |
GET | /sessions/{session_id} | Get a session with full message history |
POST | /sessions/{session_id}/messages | Send a message (queued, response via WebSocket) |
POST | /sessions/{session_id}/stream | Send 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 viaidentity_tokenwhen 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":"..."}
| Event | Fields | Description |
|---|---|---|
delta | content: string | Token chunk — concatenate all chunks to assemble the full response |
done | content: 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_result | skill: 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 |
error | code: string, message: string | Processing 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
| Event | Payload | Description |
|---|---|---|
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.
| Method | Path | Description |
|---|---|---|
GET | /chatbots | List all agents |
POST | /chatbots | Create an agent |
GET | /chatbots/{id} | Get an agent |
PUT | /chatbots/{id} | Update an agent |
DELETE | /chatbots/{id} | Delete an agent |
POST | /chatbots/{id}/assign-model | Assign 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." }
| Field | Required | Description |
|---|---|---|
name | Yes | Display name, max 100 chars |
greeting_message | No | Shown when the widget opens |
fallback_message | No | Used when the agent cannot help |
memory_enabled | No | Enable per-visitor memory |
collect_leads | No | Enable 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.
| Method | Path | Description |
|---|---|---|
GET | /skills | List workspace skills |
POST | /skills | Create a skill |
PUT | /skills/{id} | Update a skill |
DELETE | /skills/{id} | Delete a skill |
POST | /skills/{id}/test | Test 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" }
| Field | Required | Description |
|---|---|---|
name | Yes | Lowercase snake_case, max 64 chars |
description | Yes | Plain English — the AI reads this to decide when to call the skill |
parameters | No | JSON Schema object describing the parameters the AI should extract |
output_schema | No | JSON Schema of what your endpoint returns — helps the AI reason about the response |
endpoint_url | Yes | Publicly reachable URL Elaras will POST to |
api_key | No | Sent as Authorization: Bearer to your endpoint and used to sign requests |
Knowledge
| Method | Path | Description |
|---|---|---|
GET | /knowledge | List knowledge documents |
POST | /knowledge/url | Add a URL |
POST | /knowledge/crawl | Crawl a site |
POST | /knowledge/qa | Add 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}/resync | Re-fetch and re-index a document |
POST | /knowledge/{id}/clone | Clone a document |
GET | /knowledge/{id}/chunks | List 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." }
| Field | Applies to | Description |
|---|---|---|
name | All types | Rename the document, max 200 chars |
questions | Q&A only | Array of question variants (1–10), max 1000 chars each |
answer | Q&A only | The 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
| Method | Path | Description |
|---|---|---|
GET | /flows | List flows |
POST | /flows | Create a flow |
PUT | /flows/{id} | Update a flow |
DELETE | /flows/{id} | Delete a flow |
POST | /flows/generate | Generate 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.
| Method | Path | Description |
|---|---|---|
GET | /models | List personalities |
POST | /models | Create a personality |
GET | /models/{id} | Get a personality |
PUT | /models/{id} | Update a personality |
DELETE | /models/{id} | Delete a personality |
GET | /models/{id}/versions | List versions |
POST | /models/{id}/versions | Create a draft version |
PUT | /models/{id}/versions/{version_id} | Update a draft version |
POST | /models/{id}/versions/{version_id}/publish | Publish a version |
POST | /models/{id}/versions/{version_id}/clone | Clone 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.
| Method | Path | Description |
|---|---|---|
GET | /models/{id}/scenarios | List scenarios |
POST | /models/{id}/scenarios | Create a scenario |
POST | /models/{id}/scenarios/draft | Draft 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-runs | List test runs |
POST | /models/{id}/scenario-runs | Start a test run |
GET | /models/{id}/scenario-runs/compare | Compare two runs |
GET | /models/{id}/scenario-runs/{run_id} | Get run results |
POST | /models/{id}/scenario-runs/{run_id}/cancel | Cancel 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" } }
| Field | Required | Description |
|---|---|---|
name | Yes | Short human-readable title, max 200 chars |
initial_message | Yes | The first user message that starts the scenario |
category | No | Grouping tag, e.g. happy_path, edge_case, regression. Defaults to CUSTOM |
intent | No | One sentence describing what this scenario is designed to test |
turns | Yes | Array of turn objects — see below |
session_context | No | Pre-seeds the session with external identity fields before the scenario runs |
overall_criteria | No | End-of-scenario checks, e.g. {"max_turns": 6} |
Turns
Each turn has two fields:
| Field | Description |
|---|---|
bot_criteria | Checks applied to the bot's response for this turn — see below |
user_reply | The 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": [...] }.
| Field | Type | Description |
|---|---|---|
required_facts | string[] | Things the bot must say — scored by an AI judge |
prohibited | string[] | Things the bot must not say — scored by an AI judge |
expected_action | string | Skill name that must be called this turn (deterministic) |
entered_flow | integer | Flow ID the bot must have entered this turn (deterministic) |
captured | object | Flow-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.
| Field | Type | Description |
|---|---|---|
external_user_id | string | Your end-user ID |
external_profile_id | string | External profile reference |
external_org_id | string | External 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.
| Method | Path | Description |
|---|---|---|
POST | /chatbots/{id}/preview | Send 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
| Method | Path | Description |
|---|---|---|
GET | /webhooks | List webhooks |
POST | /webhooks | Create a webhook |
PUT | /webhooks/{id} | Update a webhook |
DELETE | /webhooks/{id} | Delete a webhook |
GET | /webhooks/{id}/deliveries | List delivery attempts |
POST | /webhooks/{id}/deliveries/{delivery_id}/redeliver | Retry a delivery |
POST | /webhooks/{id}/test | Send a test event |
POST | /webhooks/{id}/rotate-secret | Rotate 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." }
| Status | Meaning |
|---|---|
401 | Missing or invalid API key |
403 | Valid key but insufficient scope |
404 | Resource not found |
422 | Validation error |
429 | Rate limit exceeded |
500 | Server error — retry with backoff |
