Authentication

All API requests require a Bearer token. Include your API key in the Authorization header of every request.

Header Authorization: Bearer xln_live_YOUR_API_KEY

API keys start with xln_live_. Generate one from your Dashboard after signing up.

Keep your key secret

Never expose API keys in client-side code or public repositories. Use environment variables or a backend proxy.

Base URL

All endpoints are served from a single base URL. Append the endpoint path to this URL for every request.

Base URL https://api.xalen.io

For example, to call Chat Completions: POST https://api.xalen.io/v1/chat/completions

Quick Start

Make your first API call in under 60 seconds. Install an SDK or use cURL directly.

Python
JavaScript
cURL
pip install xalen

from xalen import Xalen

client = Xalen(api_key="xln_live_...")

response = client.chat.completions.create(
    model="vedika-standard",
    messages=[{"role": "user", "content": "Hello, world!"}]
)

print(response.choices[0].message.content)
npm install xalen-sdk

import Xalen from "xalen-sdk";

const client = new Xalen({ apiKey: "xln_live_..." });

const response = await client.chat.completions.create({
  model: "vedika-standard",
  messages: [{ role: "user", content: "Hello, world!" }],
});

console.log(response.choices[0].message.content);
curl https://api.xalen.io/v1/chat/completions \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vedika-standard",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

Chat Completions

POST /v1/chat/completions

Generate a model response for a conversation. Compatible with the OpenAI Chat Completions API format, so existing OpenAI SDK code works by changing only the base URL and API key.

Anthropic Claude models now available. Access Claude Opus 4.7, Sonnet 4.6, Opus 4.6, Haiku 4.5, Sonnet 4.5, and Claude 3.5 Haiku through the same /v1/chat/completions endpoint. No code changes needed — just set model to claude-opus-4.7, claude-sonnet-4.6, etc.

Request Body

ParameterTypeRequiredDescription
modelstringRequiredModel ID. e.g. vedika-standard, claude-sonnet-4.6, claude-opus-4.7, llama-4-maverick
messagesarrayRequiredArray of message objects with role (system, user, assistant) and content.
temperaturenumberOptionalSampling temperature between 0 and 2. Default: 1.
max_tokensintegerOptionalMaximum tokens to generate. Default: model-specific.
streambooleanOptionalStream partial responses as Server-Sent Events. Default: false.
top_pnumberOptionalNucleus sampling threshold. Default: 1.
stopstring | arrayOptionalUp to 4 sequences where the model will stop generating.

Code Examples

Python
JavaScript
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

response = client.chat.completions.create(
    model="vedika-pro",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is my birth chart?"}
    ],
    temperature=0.7,
    max_tokens=1024
)

print(response.choices[0].message.content)
import Xalen from "xalen-sdk";

const client = new Xalen({ apiKey: "xln_live_..." });

const response = await client.chat.completions.create({
  model: "vedika-pro",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is my birth chart?" },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

console.log(response.choices[0].message.content);
curl https://api.xalen.io/v1/chat/completions \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vedika-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is my birth chart?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Response

JSON Response
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717200000,
  "model": "vedika-pro",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "To generate your birth chart, I need your date, time, and place of birth..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 52,
    "total_tokens": 80
  }
}
Try it in Playground →

List Models

GET /v1/models

Returns a list of all available models. Use this to discover model IDs, capabilities, and pricing.

Code Examples

Python
JavaScript
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

models = client.models.list()
for m in models.data:
    print(m.id, m.owned_by)
import Xalen from "xalen-sdk";
const client = new Xalen({ apiKey: "xln_live_..." });

const models = await client.models.list();
models.data.forEach(m => console.log(m.id, m.owned_by));
curl https://api.xalen.io/v1/models \
  -H "Authorization: Bearer xln_live_..."

Response

JSON Response
{
  "object": "list",
  "data": [
    {
      "id": "vedika-standard",
      "object": "model",
      "owned_by": "xalen",
      "permission": []
    },
    {
      "id": "vedika-pro",
      "object": "model",
      "owned_by": "xalen",
      "permission": []
    },
    {
      "id": "claude-opus-4.7",
      "object": "model",
      "owned_by": "anthropic",
      "permission": []
    },
    {
      "id": "claude-sonnet-4.6",
      "object": "model",
      "owned_by": "anthropic",
      "permission": []
    }
  ]
}

Embeddings

POST /v1/embeddings

Generate vector embeddings for text input. Use for semantic search, clustering, or recommendation systems.

Request Body

ParameterTypeRequiredDescription
modelstringRequiredEmbedding model ID. e.g. text-embedding-3-small
inputstring | arrayRequiredText to embed. Can be a single string or array of strings.
encoding_formatstringOptionalfloat (default) or base64.

Code Examples

Python
JavaScript
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Vedic astrology birth chart analysis"
)

print(len(response.data[0].embedding))  # 1536
import Xalen from "xalen-sdk";
const client = new Xalen({ apiKey: "xln_live_..." });

const response = await client.embeddings.create({
  model: "text-embedding-3-small",
  input: "Vedic astrology birth chart analysis",
});

console.log(response.data[0].embedding.length); // 1536
curl https://api.xalen.io/v1/embeddings \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": "Vedic astrology birth chart analysis"}'

Response

JSON Response
{
  "object": "list",
  "data": [{
    "object": "embedding",
    "index": 0,
    "embedding": [0.0023, -0.0091, 0.0152, ...]
  }],
  "model": "text-embedding-3-small",
  "usage": { "prompt_tokens": 6, "total_tokens": 6 }
}

Image Generation

POST /v1/images/generations

Generate images from text prompts. Returns one or more image URLs or base64-encoded data.

Request Body

ParameterTypeRequiredDescription
promptstringRequiredText description of the image to generate.
modelstringOptionalImage model ID. Default: platform default.
nintegerOptionalNumber of images. Default: 1. Max: 4.
sizestringOptional256x256, 512x512, or 1024x1024. Default: 1024x1024.
response_formatstringOptionalurl (default) or b64_json.

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

response = client.images.generate(
    prompt="A serene Hindu temple at sunrise, watercolor style",
    size="1024x1024"
)

print(response.data[0].url)
curl https://api.xalen.io/v1/images/generations \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A serene Hindu temple at sunrise, watercolor style", "size": "1024x1024"}'

Response

JSON Response
{
  "created": 1717200000,
  "data": [{
    "url": "https://api.xalen.io/files/img-abc123.png"
  }]
}

Text to Speech

POST /v1/audio/speech

Convert text to natural-sounding speech. Supports multiple voices and output formats.

Request Body

ParameterTypeRequiredDescription
modelstringRequiredTTS model ID. e.g. tts-1, tts-1-hd
inputstringRequiredText to convert. Max 4096 characters.
voicestringRequiredVoice ID. Options: alloy, echo, fable, onyx, nova, shimmer
response_formatstringOptionalmp3 (default), opus, aac, flac, wav
speednumberOptional0.25 to 4.0. Default: 1.0.

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

response = client.audio.speech.create(
    model="tts-1",
    voice="nova",
    input="Welcome to your daily horoscope reading."
)

with open("output.mp3", "wb") as f:
    f.write(response.content)
curl https://api.xalen.io/v1/audio/speech \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{"model": "tts-1", "voice": "nova", "input": "Welcome to your daily horoscope reading."}' \
  --output output.mp3

Returns raw audio bytes in the requested format.

Speech to Text

POST /v1/audio/transcriptions

Transcribe audio to text. Supports multiple languages including 14 Indian languages.

Request Body (multipart/form-data)

ParameterTypeRequiredDescription
filefileRequiredAudio file (mp3, mp4, mpeg, mpga, m4a, wav, webm). Max 25 MB.
modelstringRequiredTranscription model. e.g. whisper-1
languagestringOptionalISO-639-1 code. e.g. hi, ta, te, en
response_formatstringOptionaljson (default), text, verbose_json

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

with open("audio.mp3", "rb") as f:
    transcript = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        language="hi"
    )

print(transcript.text)
curl https://api.xalen.io/v1/audio/transcriptions \
  -H "Authorization: Bearer xln_live_..." \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F language=hi

Response

JSON Response
{
  "text": "Transcribed text content here..."
}

Voice AI

POST /v1/voice/binary

End-to-end voice conversation: send audio, get audio back. Combines speech recognition, AI reasoning, and text-to-speech in a single call. Supports 31 languages with sub-200ms latency.

Request Body (multipart/form-data)

ParameterTypeRequiredDescription
audiofileRequiredAudio input file (wav, mp3, webm, ogg).
languagestringOptionalISO-639-1 code. Auto-detected if omitted.
voicestringOptionalResponse voice ID. Default: nova.
contextstringOptionalSystem prompt for the AI reasoning layer.
birth_detailsobjectOptionalFor astrology queries: { "date": "1990-01-15", "time": "14:30", "place": "Mumbai" }

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

with open("question.wav", "rb") as f:
    response = client.voice.binary(
        audio=f,
        language="hi",
        voice="nova"
    )

with open("answer.mp3", "wb") as f:
    f.write(response.audio)
curl https://api.xalen.io/v1/voice/binary \
  -H "Authorization: Bearer xln_live_..." \
  -F audio=@question.wav \
  -F language=hi \
  -F voice=nova \
  --output answer.mp3

Returns binary audio in mp3 format by default. The response includes a X-Transcript header with the text transcription and X-Response-Text with the AI's text reply.

Astrology AI Query

POST /v1/chat/completions

Ask any astrology question in natural language. Use model: "vedika-standard" or model: "vedika-fast" in the standard Chat Completions endpoint. The Vedika engine handles birth chart computation, classical text grounding, RAG retrieval, and multi-language response generation automatically.

Example

from xalen import Xalen

client = Xalen(api_key="xln_live_...")

response = client.chat.completions.create(
    model="vedika-standard",
    messages=[
        {"role": "user", "content": "I was born on 15 Jan 1990 at 2:30 PM in Pune. What is my current Mahadasha and its effects?"}
    ]
)

print(response.choices[0].message.content)
# Includes: grounded answer, classical citations, follow-up suggestions
curl -X POST "https://api.xalen.io/v1/chat/completions" \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vedika-standard",
    "messages": [{"role": "user", "content": "What is Rahu in the 7th house according to BPHS?"}]
  }'

The Vedika AI engine supports: birth chart analysis, dasha predictions, transit effects, compatibility matching, muhurta selection, panchang queries, yoga identification, and remedial suggestions — all through natural language conversation.

Structured Astrology Data

For structured JSON endpoints, use Vedika API directly

If you need raw structured data (birth charts, planetary positions, panchang, dasha timelines, divisional charts D1-D60, yoga calculations, compatibility scores) — the Vedika API provides 130+ computation endpoints with structured JSON responses.

✓ Birth chart (Kundali) generation
✓ Vimshottari Dasha timelines
✓ Panchang (Tithi, Nakshatra, Yoga)
✓ Ashtakoot compatibility (36 gunas)
✓ Transit & progression analysis
✓ Divisional charts (D1-D60)
✓ Yoga identification (131 yogas)
✓ Western synastry & composite

When to use XALEN vs Vedika: Use XALEN's /v1/chat/completions with vedika-standard for natural language AI queries with grounding and citations. Use Vedika's structured API directly when you need raw JSON computation data (chart objects, planetary degrees, dasha trees) for building custom UIs.

Generate a complete Vedic birth chart (Kundali) with planetary positions, house placements, nakshatras, yogas, and dashas. Powered by the Vedika Ephemeris engine with arc-second precision.

Query Parameters

ParameterTypeRequiredDescription
datestringRequiredBirth date in YYYY-MM-DD format.
timestringRequiredBirth time in HH:MM 24-hour format.
latnumberRequiredLatitude of birth place. e.g. 18.5204
lonnumberRequiredLongitude of birth place. e.g. 73.8567
tznumberOptionalTimezone offset in hours. e.g. 5.5 for IST. Auto-detected from coordinates if omitted.
systemstringOptionalvedic (default), western, or kp.
languagestringOptionalResponse language. ISO-639-1 code. Default: en.

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

chart = client.astrology.kundali(
    date="1990-01-15",
    time="14:30",
    lat=18.5204,
    lon=73.8567
)

print(chart.ascendant)       # "Taurus"
print(chart.moon_sign)       # "Scorpio"
print(chart.planets)         # Detailed planetary positions
print(chart.yogas)           # Active yogas
curl "https://api.xalen.io/v1/astrology/kundali?date=1990-01-15&time=14:30&lat=18.5204&lon=73.8567" \
  -H "Authorization: Bearer xln_live_..."

Response

JSON Response (abbreviated)
{
  "ascendant": { "sign": "Taurus", "degree": 14.32, "nakshatra": "Rohini" },
  "moon_sign": "Scorpio",
  "sun_sign": "Capricorn",
  "planets": [
    { "name": "Sun", "sign": "Capricorn", "house": 9, "degree": 0.85, "nakshatra": "Uttara Ashadha", "retrograde": false },
    { "name": "Moon", "sign": "Scorpio", "house": 7, "degree": 22.41, "nakshatra": "Jyeshtha", "retrograde": false }
  ],
  "houses": [ ... ],
  "yogas": [
    { "name": "Gaja Kesari Yoga", "description": "Jupiter in kendra from Moon", "strength": "strong" }
  ],
  "dasha": { "current": "Venus", "sub": "Mercury", "start": "2024-03-12", "end": "2026-08-04" },
  "engine": "vedika-ephemeris"
}

Kundali Matching

GET /v1/astrology/match

Compute Ashtakoot (8-fold) compatibility between two birth charts. Returns individual scores for each koot and a total out of 36.

Query Parameters

ParameterTypeRequiredDescription
boy_datestringRequiredBoy's birth date (YYYY-MM-DD).
boy_timestringRequiredBoy's birth time (HH:MM).
boy_latnumberRequiredBoy's birth latitude.
boy_lonnumberRequiredBoy's birth longitude.
girl_datestringRequiredGirl's birth date (YYYY-MM-DD).
girl_timestringRequiredGirl's birth time (HH:MM).
girl_latnumberRequiredGirl's birth latitude.
girl_lonnumberRequiredGirl's birth longitude.

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

match = client.astrology.match(
    boy_date="1990-01-15", boy_time="14:30",
    boy_lat=18.52, boy_lon=73.86,
    girl_date="1992-06-20", girl_time="09:15",
    girl_lat=19.08, girl_lon=72.88
)

print(match.total_score)  # 28.5 out of 36
curl "https://api.xalen.io/v1/astrology/match?boy_date=1990-01-15&boy_time=14:30&boy_lat=18.52&boy_lon=73.86&girl_date=1992-06-20&girl_time=09:15&girl_lat=19.08&girl_lon=72.88" \
  -H "Authorization: Bearer xln_live_..."

Response

JSON Response
{
  "total_score": 28.5,
  "max_score": 36,
  "koots": [
    { "name": "Varna", "score": 1, "max": 1 },
    { "name": "Vashya", "score": 2, "max": 2 },
    { "name": "Tara", "score": 3, "max": 3 },
    { "name": "Yoni", "score": 4, "max": 4 },
    { "name": "Graha Maitri", "score": 5, "max": 5 },
    { "name": "Gana", "score": 6, "max": 6 },
    { "name": "Bhakoot", "score": 0, "max": 7 },
    { "name": "Nadi", "score": 7.5, "max": 8 }
  ],
  "mangal_dosha": { "boy": false, "girl": false }
}

Daily Horoscope

GET /v1/astrology/horoscope

Get AI-generated daily horoscope predictions for any zodiac sign. Available in 14 Indian languages.

Query Parameters

ParameterTypeRequiredDescription
signstringRequiredZodiac sign: aries, taurus, ... pisces
datestringOptionalDate (YYYY-MM-DD). Default: today.
typestringOptionaldaily (default), weekly, monthly
languagestringOptionalISO-639-1 code. Default: en.

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

horoscope = client.astrology.horoscope(
    sign="aries",
    language="hi"
)

print(horoscope.prediction)
curl "https://api.xalen.io/v1/astrology/horoscope?sign=aries&language=hi" \
  -H "Authorization: Bearer xln_live_..."

Response

JSON Response
{
  "sign": "aries",
  "date": "2026-05-08",
  "prediction": "Today brings favorable energy for career decisions...",
  "lucky_number": 7,
  "lucky_color": "Red",
  "mood": "Energetic"
}

Dasha Predictions

GET /v1/astrology/dasha

Calculate the Vimshottari Dasha timeline for a birth chart. Returns Mahadasha, Antardasha, and Pratyantardasha periods with start/end dates.

Query Parameters

ParameterTypeRequiredDescription
datestringRequiredBirth date (YYYY-MM-DD).
timestringRequiredBirth time (HH:MM).
latnumberRequiredBirth latitude.
lonnumberRequiredBirth longitude.

Code Examples

Python
cURL
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

dasha = client.astrology.dasha(
    date="1990-01-15",
    time="14:30",
    lat=18.5204,
    lon=73.8567
)

for period in dasha.mahadasha:
    print(f"{period.planet}: {period.start} to {period.end}")
curl "https://api.xalen.io/v1/astrology/dasha?date=1990-01-15&time=14:30&lat=18.5204&lon=73.8567" \
  -H "Authorization: Bearer xln_live_..."

Response

JSON Response (abbreviated)
{
  "mahadasha": [
    { "planet": "Venus", "start": "1990-01-15", "end": "2010-01-15", "years": 20 },
    { "planet": "Sun", "start": "2010-01-15", "end": "2016-01-15", "years": 6 },
    { "planet": "Moon", "start": "2016-01-15", "end": "2026-01-15", "years": 10 }
  ],
  "current": {
    "mahadasha": "Moon",
    "antardasha": "Venus",
    "pratyantardasha": "Mercury"
  }
HIDDEN_END -->

      
      

        
Run Agent

        

          POST
          /v1/agents/run
        

        
Execute a pre-built AI agent with a single API call. Agents are purpose-built for specific tasks like temple management, devotional content, and spiritual guidance.


        
Request Body

        

          
ParameterTypeRequiredDescription

          
            
agent_idstringRequiredAgent identifier. e.g. temple-assistant, kundali-reader, puja-planner

            
inputstringRequiredUser message or task description.

            
contextobjectOptionalAdditional data for the agent (birth details, location, preferences).

            
streambooleanOptionalStream the response. Default: false.

          
        


        
Code Examples

        

          

            
Python

            
cURL

          

          

            
            
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

result = client.agents.run(
    agent_id="kundali-reader",
    input="What career paths suit my chart?",
    context={
        "birth_date": "1990-01-15",
        "birth_time": "14:30",
        "birth_place": "Pune, India"
    }
)

print(result.output)

          

          

            
            
curl https://api.xalen.io/v1/agents/run \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "kundali-reader",
    "input": "What career paths suit my chart?",
    "context": {"birth_date": "1990-01-15", "birth_time": "14:30", "birth_place": "Pune, India"}
  }'

          

        


        
Response

        

          
JSON Response

          
{
  "agent_id": "kundali-reader",
  "output": "Based on your chart with Taurus ascendant and strong 10th house...",
  "usage": { "prompt_tokens": 450, "completion_tokens": 320, "total_tokens": 770 }
}

        

      


      
      

        
Check Balance

        

          GET
          /v1/billing/balance
        

        
Retrieve your current wallet balance and usage summary.


        
Code Examples

        

          

            
Python

            
cURL

          

          

            
            
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

balance = client.billing.balance()
print(f"${balance.available / 100:.2f}")  # Wallet in USD

          

          

            
            
curl https://api.xalen.io/v1/billing/balance \
  -H "Authorization: Bearer xln_live_..."

          

        


        
Response

        

          
JSON Response

          
{
  "available": 4250,
  "currency": "usd_cents",
  "total_spent": 1750,
  "plan": "pay-as-you-go"
}

        

      


      
      

        
Add Funds

        

          POST
          /v1/billing/deposit
        

        
Add funds to your wallet. Returns a Razorpay payment link. Minimum deposit: $10.


        
Request Body

        

          
ParameterTypeRequiredDescription

          
            
amountintegerRequiredAmount in USD cents. Minimum: 1000 ($10).

            
currencystringOptionalusd (default) or inr.

          
        


        
Code Examples

        

          

            
Python

            
cURL

          

          

            
            
from xalen import Xalen

client = Xalen(api_key="xln_live_...")

payment = client.billing.deposit(amount=5000)  # $50
print(payment.payment_url)  # Razorpay checkout link

          

          

            
            
curl https://api.xalen.io/v1/billing/deposit \
  -H "Authorization: Bearer xln_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000}'

          

        


        
Response

        

          
JSON Response

          
{
  "payment_id": "pay_abc123",
  "payment_url": "https://rzp.io/l/xalen-deposit",
  "amount": 5000,
  "currency": "usd_cents",
  "status": "pending"
}

        

      


      
      

        
SDKs

        
Official client libraries for Python, JavaScript, and an MCP server for AI coding assistants.


        
Python

        

          

            
            
pip install xalen

          

        

        

          

            
            
from xalen import Xalen

# Uses XALEN_API_KEY env var by default
client = Xalen()

# Or pass explicitly
client = Xalen(api_key="xln_live_...")

# All OpenAI-compatible methods work
response = client.chat.completions.create(
    model="vedika-standard",
    messages=[{"role": "user", "content": "Hello"}]
)

          

        


        
JavaScript / TypeScript

        

          

            
            
npm install xalen-sdk

          

        

        

          

            
            
import Xalen from "xalen-sdk";

const client = new Xalen({ apiKey: process.env.XALEN_API_KEY });

const response = await client.chat.completions.create({
  model: "vedika-standard",
  messages: [{ role: "user", content: "Hello" }],
});

          

        


        
MCP Server

        
Connect XALEN to AI coding assistants like Claude Code, Cursor, and GitHub Copilot using the Model Context Protocol.

        

          

            
            
npx xalen-mcp

          

        

        
The MCP server exposes 15 tools covering chat, embeddings, image generation, voice, astrology, and billing. See the npm package for configuration details.

      


      
      

        
Errors

        
XALEN uses standard HTTP status codes. All error responses include a JSON body with error.type and error.message.


        

          
StatusTypeDescription

          
            
400invalid_requestMissing or invalid parameters.

            
401authentication_errorInvalid or missing API key.

            
403permission_deniedKey lacks permission for this endpoint.

            
404not_foundEndpoint or resource not found.

            
429rate_limit_exceededToo many requests. Retry after the time in Retry-After header.

            
500server_errorInternal error. Contact support if persistent.

            
503service_unavailableTemporary overload. Retry with exponential backoff.

          
        


        
Error Response Format

        

          
JSON Error

          
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Keys must start with xln_live_.",
    "status": 401
  }
}

        


        

          Retry Strategy
          
For 429 and 503 errors, use exponential backoff starting at 1 second. The SDKs handle this automatically with up to 3 retries.

        

      


      
      

        
Rate Limits

        
Rate limits are applied per API key and vary by plan. Limits are returned in response headers.


        

          
PlanRPMTPM

          
            
Pay-as-you-go60 RPM100K TPM

            
Growth300 RPM500K TPM

            
Scale1,000 RPM2M TPM

            
Dedicated5,000 RPM10M TPM

            
EnterpriseCustomCustom

          
        


        
Rate Limit Headers

        

          
HeaderDescription

          
            
x-ratelimit-limit-requestsMaximum requests per minute for your plan.

            
x-ratelimit-remaining-requestsRemaining requests in the current window.

            
x-ratelimit-reset-requestsSeconds until the request limit resets.

            
x-ratelimit-limit-tokensMaximum tokens per minute for your plan.

            
x-ratelimit-remaining-tokensRemaining tokens in the current window.