Developer API

The Developer API is a server-side REST API for managing chat sessions and sending messages programmatically. It is authenticated with a team secret key (sk_...) and should only ever be called from your server — never from client-side code.

Creating an API key

1. Go to Developer > API Keys in the Elaras dashboard.
2. Click Create API key and give it a descriptive name (e.g. "Production backend").
3. Copy the key immediately — it is only shown once.

API keys are scoped to your team and have access to all chatbots in the team.

Authentication

Pass your secret key as a Bearer token in every request:

Authorization: Bearer sk_live_your_key_here

# Example with curl
curl https://api.elaras.ai/api/developer/v1/sessions \
  -H "Authorization: Bearer sk_live_your_key_here"

Base URL

https://api.elaras.ai/api

Endpoints

List sessions

Returns a paginated list of all sessions across all chatbots for your team.

GET /developer/v1/sessions

Query parameters:

Example request:

curl "https://api.elaras.ai/api/developer/v1/sessions?per_page=25&chatbot_id=cbt_abc123" \
  -H "Authorization: Bearer sk_live_your_key_here"

Example response:

{
  "data": [
    {
      "session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "messages": [
        {
          "id": 1,
          "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "role": "user",
          "content": "What are your opening hours?",
          "credits_used": null,
          "feedback": null,
          "created_at": "2026-07-24T10:29:58Z"
        },
        {
          "id": 2,
          "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "role": "assistant",
          "content": "We are open Monday to Friday, 9am to 5pm.",
          "credits_used": 3,
          "feedback": "up",
          "created_at": "2026-07-24T10:30:01Z"
        }
      ]
    }
  ],
  "total": 120,
  "per_page": 25,
  "current_page": 1
}

Get a session

Returns a single session with its full message history.

GET /developer/v1/sessions/{session_id}

Path parameters:

Example request:

curl "https://api.elaras.ai/api/developer/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer sk_live_your_key_here"

Example response:

{
  "session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "messages": [
    {
      "id": 1,
      "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "role": "user",
      "content": "What are your opening hours?",
      "credits_used": null,
      "feedback": null,
      "created_at": "2026-07-24T10:29:58Z"
    }
  ]
}

Send a message to a session

Sends a message to a session server-side. The AI processes it and delivers the response via WebSocket to the session's channel — the response is not included in the HTTP response body.

This is useful for proactive messages (notifying a user when their order ships), backend-triggered conversations, or injecting context into a session before a user starts chatting.

POST /developer/v1/sessions/{session_id}/messages

Path parameters:

Request body:

{
  "message": "Your order #12345 has shipped! Expected delivery: 26 July.",
  "chatbot_key": "cbt_abc123"
}

Example request:

curl -X POST "https://api.elaras.ai/api/developer/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Your order has shipped!",
    "chatbot_key": "cbt_abc123"
  }'

Example response:

{
  "ok": true
}

The AI response is delivered asynchronously via WebSocket to the channel chat.{session_id}. If the user has the widget or SDK open, they will receive the response in real time.

Node.js example

// Send a proactive message when an order ships
async function notifyOrderShipped(sessionId: string, orderId: string) {
  const response = await fetch(
    `https://api.elaras.ai/api/developer/v1/sessions/${sessionId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ELARAS_SECRET_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        message: `Your order #${orderId} has shipped! I can help you track it or answer any questions.`,
        chatbot_key: process.env.ELARAS_CHATBOT_KEY,
      }),
    },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Elaras API error: ${error.message}`);
  }

  return response.json();
}

PHP example

<?php

function sendElarasMessage(string $sessionId, string $message, string $chatbotKey): void
{
    $url = "https://api.elaras.ai/api/developer/v1/sessions/{$sessionId}/messages";

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('ELARAS_SECRET_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode([
            'message'     => $message,
            'chatbot_key' => $chatbotKey,
        ]),
    ]);

    $response = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        $body = json_decode($response, true);
        throw new \RuntimeException('Elaras API error: ' . $body['message']);
    }
}

// Usage — e.g. in an order shipped event handler
sendElarasMessage(
    $user->elaras_session_id,
    "Your order #{$order->id} has shipped!",
    config('services.elaras.chatbot_key'),
);

Skills API

You can manage skills programmatically instead of through the dashboard — useful for multi-tenant setups where each customer needs their own skill configuration.

List chatbots

GET /developer/v1/chatbots

Returns all chatbots for your team. Use the id field in the skill routes below.

curl "https://api.elaras.ai/api/developer/v1/chatbots" \
  -H "Authorization: Bearer sk_live_your_key_here"

List skills

GET /developer/v1/chatbots/{chatbot_id}/skills

Create a skill

POST /developer/v1/chatbots/{chatbot_id}/skills

Request body:

{
  "name": "get_order_status",
  "description": "Look up the status of a customer order by order ID. Call this when the user asks about their order, delivery, or shipment.",
  "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_secret_key",
  "enabled": true
}

Update a skill

PUT /developer/v1/chatbots/{chatbot_id}/skills/{skill_id}

Same fields as create — all are optional (partial update).

Delete a skill

DELETE /developer/v1/chatbots/{chatbot_id}/skills/{skill_id}

Returns 204 No Content.

Use cases

Proactive notifications — When an event happens in your system (order shipped, appointment reminder, support ticket updated), send a message to the user's session so they see it the next time they open the chat.

Backend-triggered conversations — Create sessions and prime them with context before the user starts chatting. For example, inject the user's account details and recent orders so the AI can answer questions without asking for information the user has already provided.

CRM integrations — Read session data via GET /developer/sessions and sync conversations into your CRM, helpdesk, or data warehouse.

Admin tooling — Build internal tools that let your team view chat sessions, inspect what the AI said, or send messages on behalf of the chatbot.

Error responses

All errors follow the same shape:

{
  "message": "Human-readable error description.",
  "code": "OPTIONAL_ERROR_CODE"
}