Skip to main content
The XUNA AI Conversational AI API uses API keys for server-side requests and short-lived tokens for client-side connections. Choose the right method depending on where your code runs.

​
API key

Your API key authenticates every direct HTTP request to the API. Pass it in the xi-api-key header: 
curl https://api.xuna.ai/v1/convai/agents \
  -H "xi-api-key: YOUR_API_KEY"
Get your key from Settings → API Keys.
Never expose your API key in client-side code, browser bundles, or mobile apps. Use signed URLs or conversation tokens for any code that runs outside your server.
Store the key as an environment variable: 
export XUNA_AI_API_KEY=your_api_key_here
The SDKs read XUNA_AI_API_KEY automatically: 
from xuna_ai.client import XunaAI

# Reads XUNA_AI_API_KEY from the environment
client = XunaAI()

​
Signed URLs (WebSocket)

A signed URL is a pre-authenticated wss:// address your server generates on demand. Pass it to a browser or mobile client so it can open a WebSocket connection without needing your API key.

​
Get a signed URL

GET /v1/convai/conversation/get-signed-url?agent_id={agent_id}
​
agent_id
string
required
The ID of the agent you want to start a conversation with.
response = client.conversational_ai.conversations.get_signed_url(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
signed_url = response.signed_url
print(signed_url)  # wss://...
Response:
​
signed_url
string
required
A pre-authenticated WebSocket URL (wss://). Valid for a short window — generate one per session.
Generate a fresh signed URL for every new conversation. Signed URLs are single-use and expire quickly.

​
Conversation tokens (WebRTC)

A conversation token serves the same purpose as a signed URL but for WebRTC-based connections. Your server exchanges your API key for a short-lived token and hands it to the client.

​
Get a conversation token

GET /v1/convai/conversation/token?agent_id={agent_id}
​
agent_id
string
required
The ID of the agent to start a conversation with.
response = client.conversational_ai.conversations.get_token(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
token = response.token
print(token)
Response:
​
token
string
required
A short-lived token your client passes when initiating a WebRTC connection.

​
Choosing an auth method

Use caseMethod
Server-to-server API callsAPI key in xi-api-key header
Browser WebSocket connectionSigned URL
Browser / mobile WebRTC connectionConversation token