Kura API Documentation

Integrate AI-powered voice and chat into your applications with our REST + WebSocket API.

How it works

Every integration follows a two-step pattern:

Create a session via REST (POST /api/v1/sessions)
Connect a WebSocket to the returned URL for real-time voice or chat

                    
                        // Flow diagram

                        Your App ──POST /api/v1/sessions──► Kura Backend

                                 ◄── { session_id, websocket_url } ──┘

                        Your App ──WebSocket(websocket_url)──► Kura Backend

                                 ◄──► bidirectional audio/text ──┘

Authentication

All requests require an API key generated from the Kura dashboard (Settings → API Keys).

REST requests

Authorization: Bearer kura_live_xxxxxxxxxxxxxxxxxx

WebSocket connections

The API key is embedded in the websocket_url returned by session creation. No extra auth step needed.

Required Permissions

Permission	Purpose
`sessions:create`	Create new sessions
`sessions:connect`	Connect WebSocket
`assistants:read`	Load assistant config

Quick Start

Create a voice session and connect in under 10 lines of code.

                    import requests, websocket

# 1. Create session
session = requests.post(
    "https://api.yourdomain.com/api/v1/sessions",
    headers={"Authorization": "Bearer kura_live_xxx"},
    json={"assistant_id": 1, "mode": "voice"}
).json()

# 2. Connect WebSocket
ws = websocket.create_connection(session["websocket_url"])

# 3. Send audio, receive AI responses
ws.send(json.dumps({"type": "audioChunk", "audio": base64_pcm_data}))
                

Create Session

POST /api/v1/sessions

Request Body

Field	Type	Required	Description
`assistant_id`	integer	Yes	Assistant ID from dashboard
`mode`	string	No	"voice" (default) or "chat"
`phone_number`	string	No	Caller number for contact tracking
`language_code`	string	No	BCP-47 code, default "en-US"
`metadata`	object	No	Custom metadata attached to session

Response (201)

                    {
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "voice",
  "websocket_url": "ws://host:8080/api/v1/sessions/550e.../connect?api_key=...",
  "expires_at": "2026-01-26T12:05:00Z",
  "assistant": { "id": 1, "name": "Customer Support" }
}
                

Connect the WebSocket within 5 minutes or the session expires.

All Endpoints

Method	Endpoint	Description
GET	`/api/v1/health`	Health check
GET	`/api/v1/assistants`	List assistants
GET	`/api/v1/assistants/:id`	Get assistant details
POST	`/api/v1/sessions`	Create session
GET	`/api/v1/sessions/:id`	Get session status
DELETE	`/api/v1/sessions/:id`	End session

Rate Limiting

Default: 60 requests/minute per API key. Check response headers:

                    X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1706270400
                

WebSocket Protocol

After creating a session, connect to the websocket_url for bidirectional communication.

Audio Format

Property	Value
Encoding	Linear PCM, 16-bit signed, little-endian
Sample rate	24,000 Hz
Channels	Mono (1)
Transport	Base64-encoded over JSON

Message Types

Client → Server

                    // Send audio (voice mode)
{ "type": "audioChunk", "audio": "<base64_pcm16_24khz>" }

// Send text (chat mode)
{ "type": "textMessage", "text": "Hello" }

// Interrupt agent speech
{ "type": "interrupt" }

// End session
{ "type": "stopSession" }
                

Server → Client

                    // Session ready
{ "type": "sessionOpen", "provider": "gemini", "mode": "voice" }

// Agent audio (voice mode)
{ "type": "agentAudioChunk", "audio": "<base64>" }

// Real-time transcription
{ "type": "transcriptionUpdate", "source": "input|output", "text": "..." }

// Turn finished
{ "type": "turnComplete", "fullInput": "...", "fullOutput": "..." }

// Session idle timeout
{ "type": "sessionTimeout", "reason": "idle", "timeoutSeconds": 120 }

// Error
{ "type": "sessionError", "error": "..." }
                

Chat Embed Widget

Add a live AI chat assistant to any website with a single script tag.

                    <script
  src="https://app.yourdomain.com/embed/chat-widget.js"
  data-api-key="kura_live_xxx"
  data-assistant-id="1"
  data-backend-url="https://api.yourdomain.com"
  data-theme="light"
  data-primary-color="#6366F1"
  data-title="Chat Support"
></script>
                

Configuration

Attribute	Default	Description
`data-api-key`	required	API key with chat permissions
`data-assistant-id`	required	Assistant ID (must support chat)
`data-backend-url`	required	Backend URL
`data-theme`	light	light or dark
`data-position`	bottom-right	bottom-right or bottom-left
`data-primary-color`	#6366F1	Primary color (hex)

Webhooks

When an AI assistant calls a webhook tool during a conversation, Kura sends a POST request to your configured URL.

Webhook Payload

                    {
  "tool_name": "book_appointment",
  "tool_args": {
    "customer_name": "John Smith",
    "date": "2026-02-15"
  },
  "assistant_id": 1,
  "timestamp": "2026-02-13T10:30:00.000Z"
}
                

Python

pip install websocket-client requests pyaudio

                    import json, base64, threading, requests, websocket, pyaudio

KURA_HOST = "https://api.yourdomain.com"
API_KEY = "kura_live_xxxxxxxxxxxxxxxxxx"
ASSISTANT_ID = 1
SAMPLE_RATE = 24000

# Create session
session = requests.post(
    f"{KURA_HOST}/api/v1/sessions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"assistant_id": ASSISTANT_ID, "mode": "voice"},
).json()

# Connect and handle messages
ws = websocket.WebSocketApp(
    session["websocket_url"],
    on_message=lambda ws, msg: print(json.loads(msg)),
)
ws.run_forever()
                

JavaScript / Node.js

npm install ws

                    import WebSocket from 'ws';

const KURA_HOST = 'https://api.yourdomain.com';
const API_KEY = 'kura_live_xxxxxxxxxxxxxxxxxx';

// Create session
const res = await fetch(`${KURA_HOST}/api/v1/sessions`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: JSON.stringify({ assistant_id: 1, mode: 'chat' }),
});
const session = await res.json();

// Connect WebSocket
const ws = new WebSocket(session.websocket_url);
ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString());
  console.log(msg.type, msg);
});
                

More Languages

Full working examples are available for all major languages:

Go

gorilla/websocket + net/http

Rust

tokio-tungstenite + reqwest

C# / .NET

ClientWebSocket + HttpClient

Java

Java-WebSocket + Gson

Dart / Flutter

web_socket_channel + http

cURL

websocat for WebSocket testing

Contact us for complete code samples for your language.

Error Handling

Error	Code	Recovery
Invalid API key	`401`	Check key, regenerate if expired
Insufficient permissions	`403`	Add required permissions to key
Session expired	`404`	Create a new session
Rate limit exceeded	`429`	Wait for Retry-After seconds
WebSocket disconnect	`-`	Create new session and reconnect