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://api.elaras.ai/api/developer/v1

Rate limits

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

Sessions

Read conversations and send messages programmatically.

Method	Path	Description
`GET`	`/sessions`	List all sessions for your team
`GET`	`/sessions/{session_id}`	Get a session with full message history
`POST`	`/sessions/{session_id}/messages`	Send a message to a session

Send a message

POST /sessions/{session_id}/messages

{ "message": "Your order has shipped!" }

The AI processes the message and delivers its response asynchronously to the session's WebSocket channel. If the visitor has the widget open they receive it in 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 with custom params
`GET`	`/chatbots/{id}/skills`	List skills attached to an agent
`POST`	`/chatbots/{id}/skills`	Attach a skill to an agent
`PUT`	`/chatbots/{id}/skills/{skill_id}`	Update an agent-skill attachment
`DELETE`	`/chatbots/{id}/skills/{skill_id}`	Detach a skill from an agent

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
`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." }

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
`POST`	`/chatbots/{id}/flows/{flow_id}/attach`	Attach a flow 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 (model-scoped) or directly to an agent.

Model-scoped:

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

Agent-scoped:

Method	Path	Description
`GET`	`/chatbots/{id}/scenarios`	List scenarios
`POST`	`/chatbots/{id}/scenarios`	Create a scenario
`POST`	`/chatbots/{id}/scenarios/draft`	Draft scenarios with AI
`GET`	`/chatbots/{id}/scenarios/{scenario_id}`	Get a scenario
`PUT`	`/chatbots/{id}/scenarios/{scenario_id}`	Update a scenario
`DELETE`	`/chatbots/{id}/scenarios/{scenario_id}`	Delete a scenario
`GET`	`/chatbots/{id}/scenario-runs`	List test runs
`POST`	`/chatbots/{id}/scenario-runs`	Start a test run
`GET`	`/chatbots/{id}/scenario-runs/{run_id}`	Get run results
`POST`	`/chatbots/{id}/scenario-runs/{run_id}/cancel`	Cancel a run

Preview

Send a message to an agent's draft personality for testing, with a full reasoning trace in the response.

Method	Path	Description
`POST`	`/chatbots/{id}/preview`	Send a preview message
`DELETE`	`/chatbots/{id}/preview/{session_token}`	Clear a preview session

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