--- title: Developer API sidebar_position: 7 --- # 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: ```http Authorization: Bearer sk_live_your_key_here ``` ```bash # 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. ```http GET /developer/v1/sessions ``` **Query parameters:** | Parameter | Type | Default | Description | |---|---|---|---| | `page` | integer | `1` | Page number | | `per_page` | integer | `15` | Results per page (max 100) | | `chatbot_id` | string | — | Filter by chatbot key (`cbt_...`) | **Example request:** ```bash 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:** ```json { "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. ```http GET /developer/v1/sessions/{session_id} ``` **Path parameters:** | Parameter | Description | |---|---| | `session_id` | Session UUID | **Example request:** ```bash curl "https://api.elaras.ai/api/developer/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \ -H "Authorization: Bearer sk_live_your_key_here" ``` **Example response:** ```json { "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. ```http POST /developer/v1/sessions/{session_id}/messages ``` **Path parameters:** | Parameter | Description | |---|---| | `session_id` | Session UUID. Generate a UUID server-side and store it alongside the user record in your system. | **Request body:** ```json { "message": "Your order #12345 has shipped! Expected delivery: 26 July.", "chatbot_key": "cbt_abc123" } ``` | Field | Type | Required | Description | |---|---|---|---| | `message` | string | Yes | The message content to send | | `chatbot_key` | string | Conditional | Required if the session does not exist yet. The `cbt_...` key of the chatbot to use. | **Example request:** ```bash 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:** ```json { "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 ```ts // 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 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 ```http GET /developer/v1/chatbots ``` Returns all chatbots for your team. Use the `id` field in the skill routes below. ```bash curl "https://api.elaras.ai/api/developer/v1/chatbots" \ -H "Authorization: Bearer sk_live_your_key_here" ``` --- ### List skills ```http GET /developer/v1/chatbots/{chatbot_id}/skills ``` --- ### Create a skill ```http POST /developer/v1/chatbots/{chatbot_id}/skills ``` **Request body:** ```json { "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 } ``` | Field | Type | Required | Description | |---|---|---|---| | `name` | string | Yes | Lowercase `snake_case`, max 64 chars. This is the function name the AI uses. | | `description` | string | Yes | Plain English explanation. The AI reads this to decide when to call the skill. | | `parameters` | object | No | [JSON Schema](https://json-schema.org) object describing the parameters the AI should extract. | | `endpoint_url` | string | Yes | The URL Elaras will POST to when the AI calls this skill. Must be publicly reachable. | | `api_key` | string | No | Sent as `Authorization: Bearer ` to your endpoint. Stored encrypted. | | `enabled` | boolean | No | Defaults to `true`. | --- ### Update a skill ```http PUT /developer/v1/chatbots/{chatbot_id}/skills/{skill_id} ``` Same fields as create — all are optional (partial update). --- ### Delete a skill ```http 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: ```json { "message": "Human-readable error description.", "code": "OPTIONAL_ERROR_CODE" } ``` | HTTP status | Meaning | |---|---| | `401` | Missing or invalid `sk_` key | | `404` | Session or resource not found | | `422` | Validation error (check `message` for details) | | `429` | Rate limit exceeded — back off and retry | | `500` | Elaras server error — retry with exponential backoff |