API Reference

Base URL

https://api.pureai-api.com

Authentication

All inference endpoints accept two authentication methods:

Method	Header	Format
API Key	`x-api-key`	`pk_live_...`
JWT	`Authorization`	`Bearer <token>`

# API Key
curl -H "x-api-key: pk_live_YOUR_KEY" ...

# JWT (from Cognito)
curl -H "Authorization: Bearer eyJhbG..." ...

API keys are created in the Lunar Console. The SDK reads from the LUNAR_API_KEY environment variable by default.

POST /v1/chat/completions

Create a chat completion. OpenAI-compatible. Request Body:

Field	Type	Required	Description
`model`	`string`	Yes	Model ID (e.g. `gpt-4o-mini`) or `provider/model` to force a provider (e.g. `openai/gpt-4o-mini`)
`messages`	`array`	Yes	Array of `{role, content}` objects. Roles: `system`, `user`, `assistant`
`stream`	`boolean`	No	Enable SSE streaming (default: `false`)
`max_tokens`	`integer`	No	Maximum tokens to generate
`temperature`	`float`	No	Sampling temperature (0-2, default: 0.7)
`top_p`	`float`	No	Nucleus sampling (default: 1.0)
`stop`	`array`	No	Stop sequences
`presence_penalty`	`float`	No	Presence penalty (default: 0.0)
`frequency_penalty`	`float`	No	Frequency penalty (default: 0.0)
`n`	`integer`	No	Number of choices (default: 1)
`provider`	`string`	No	Force a specific provider
`fallbacks`	`array`	No	Fallback models if primary fails (SDK only)

Standard
Streaming
Force Provider
Custom Deployment

curl -X POST "https://api.pureai-api.com/v1/chat/completions" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are helpful."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7
  }'

Response:

{
  "id": "chatcmpl_a1b2c3d4",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21,
    "input_cost_usd": 0.000018,
    "output_cost_usd": 0.000027,
    "cache_input_cost_usd": 0.0,
    "total_cost_usd": 0.000045,
    "latency_ms": 523.4,
    "ttft_ms": 215.2
  }
}

curl -X POST "https://api.pureai-api.com/v1/chat/completions" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Response (Server-Sent Events):

data: {"id":"chatcmpl_a1b2","object":"chat.completion.chunk","model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant"}}]}

data: {"id":"chatcmpl_a1b2","object":"chat.completion.chunk","model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl_a1b2","object":"chat.completion.chunk","model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"!"}}]}

data: {"id":"chatcmpl_a1b2","object":"chat.completion.chunk","model":"gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Use the provider/model format to bypass routing and send directly to a specific provider:

curl -X POST "https://api.pureai-api.com/v1/chat/completions" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Use the pureai/ prefix to use your own GPU-deployed models:

curl -X POST "https://api.pureai-api.com/v1/chat/completions" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pureai/gemma-3-4b-it",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Custom deployments use inference-time pricing (GPU time) instead of per-token pricing.

POST /v1/completions

Create a text completion (legacy endpoint). Request Body:

Field	Type	Required	Description
`model`	`string`	Yes	Model ID or `provider/model`
`prompt`	`string`	Yes	Text prompt
`max_tokens`	`integer`	No	Maximum tokens (default: 1024)
`temperature`	`float`	No	Sampling temperature (default: 0.7)
`stop`	`array`	No	Stop sequences
`stream`	`boolean`	No	Enable SSE streaming (default: `false`)

Standard
Streaming

curl -X POST "https://api.pureai-api.com/v1/completions" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "prompt": "The capital of France is",
    "max_tokens": 50,
    "temperature": 0.7
  }'

Response:

{
  "id": "cmpl_a1b2c3d4",
  "object": "text_completion",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "text": " Paris, the city of light.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 7,
    "total_tokens": 12,
    "input_cost_usd": 0.000008,
    "output_cost_usd": 0.000021,
    "total_cost_usd": 0.000029,
    "latency_ms": 312.1,
    "ttft_ms": 180.5
  }
}

curl -X POST "https://api.pureai-api.com/v1/completions" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "prompt": "Hello",
    "max_tokens": 1024,
    "stream": true
  }'

Response (Server-Sent Events):

data: {"id":"cmpl_a1b2","object":"text_completion.chunk","choices":[{"index":0,"text":"Hello"}]}

data: {"id":"cmpl_a1b2","object":"text_completion.chunk","choices":[{"index":0,"text":" there"}]}

data: {"id":"cmpl_a1b2","object":"text_completion.chunk","choices":[{"index":0,"text":"!","finish_reason":"stop"}]}

data: [DONE]

POST /v1/router

Intelligent routing endpoint. Analyzes the prompt semantically and selects the optimal model using the UniRoute algorithm. Request Body:

Field	Type	Required	Description
`messages`	`array`	Yes	Array of `{role, content}` objects (min 1)
`execute`	`boolean`	No	Execute after routing (default: `true`). Set `false` to only get the routing decision
`models`	`array`	No	Restrict routing to specific models (min 2). If omitted, uses all available models
`cost_weight`	`float`	No	Cost penalty weight (default: 0.0). `0` = ignore cost, higher = prefer cheaper models
`stream`	`boolean`	No	Enable SSE streaming when `execute=true` (default: `false`)
`max_tokens`	`integer`	No	Maximum tokens when `execute=true`
`temperature`	`float`	No	Temperature when `execute=true` (0-2)

Auto Route + Execute
Restricted Models
Decision Only

Routes among all available models and executes:

curl -X POST "https://api.pureai-api.com/v1/router" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write a haiku about programming"}
    ]
  }'

Response:

{
  "id": "router-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "routing": {
    "selected_model": "gpt-4o-mini",
    "selected_provider": "openai",
    "expected_error": 0.12,
    "cost_adjusted_score": 0.12,
    "cluster_id": 3,
    "reasoning": "Simple creative task — lightweight model sufficient"
  },
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Lines of code align\nBugs emerge from morning mist\nFixed by afternoon"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 18,
    "total_tokens": 28,
    "total_cost_usd": 0.00002
  }
}

Route among specific models only:

curl -X POST "https://api.pureai-api.com/v1/router" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write Python code to sort a list"}
    ],
    "models": ["gpt-4o-mini", "codestral-latest"],
    "cost_weight": 0.5
  }'

Get routing decision without executing:

curl -X POST "https://api.pureai-api.com/v1/router" \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is the capital of Brazil?"}
    ],
    "execute": false
  }'

Response:

{
  "id": "router-xyz",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "routing": {
    "selected_model": "gpt-4o-mini",
    "selected_provider": "openai",
    "expected_error": 0.05,
    "cost_adjusted_score": 0.05,
    "cluster_id": 1,
    "all_scores": {
      "gpt-4o-mini": 0.05,
      "gpt-4o": 0.03,
      "mistral-small-latest": 0.08
    },
    "reasoning": "Simple factual question — lightweight model optimal"
  },
  "choices": []
}

GET /v1/router/profiles

List models that have semantic routing profiles available.

curl "https://api.pureai-api.com/v1/router/profiles" \
  -H "x-api-key: pk_live_YOUR_KEY"

Response:

{
  "profiles": [
    "gpt-4o",
    "gpt-4o-mini",
    "gpt-4-turbo",
    "gpt-3.5-turbo",
    "mistral-large-latest",
    "mistral-small-latest"
  ],
  "count": 6
}

GET /v1/providers

List providers available for a model. Query Parameters:

Field	Type	Required	Description
`model`	`string`	No	Model ID (defaults to `gpt-4o-mini`)

curl "https://api.pureai-api.com/v1/providers?model=gpt-4o-mini" \
  -H "x-api-key: pk_live_YOUR_KEY"

Response:

[
  {
    "id": "openai",
    "type": "primary",
    "enabled": true,
    "params": {}
  },
  {
    "id": "groq",
    "type": "backup",
    "enabled": true,
    "params": {}
  }
]

Response Objects

Usage

Included in all completion responses. Extends the OpenAI format with cost and latency data.

Field	Type	Description
`prompt_tokens`	`int`	Input token count
`completion_tokens`	`int`	Output token count
`total_tokens`	`int`	Total tokens
`input_cost_usd`	`float`	Input cost in USD
`output_cost_usd`	`float`	Output cost in USD
`cache_input_cost_usd`	`float`	Cached input cost in USD
`total_cost_usd`	`float`	Total cost in USD
`latency_ms`	`float`	Total request latency in ms
`ttft_ms`	`float`	Time to first token in ms

Error Response

{
  "detail": "All providers failed for model 'invalid-model': Model not found"
}

Rate Limits

Rate limits are applied per API key. When exceeded, you receive a 429 response with a retry_after field in the body.

SDK Usage

Python
TypeScript

from lunar import Lunar

client = Lunar(api_key="pk_live_YOUR_KEY")

# Chat completions
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
print(f"Cost: ${response.usage.total_cost_usd}")

# With fallbacks
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
    fallbacks=["claude-3-haiku", "llama-3.1-8b"]
)

# Streaming
for chunk in client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=True
):
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

# Text completions
response = client.completions.create(
    model="gpt-4o-mini",
    prompt="Hello"
)

# List models
models = client.models.list()

# List providers
providers = client.providers.list(model="gpt-4o-mini")

import { Lunar } from "lunar";

const client = new Lunar({ apiKey: "pk_live_YOUR_KEY" });

// Chat completions
const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);
console.log(`Cost: $${response.usage?.total_cost_usd}`);

// With fallbacks
const response2 = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
  fallbacks: ["claude-3-haiku", "llama-3.1-8b"],
});

// Streaming
const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
});
for await (const chunk of stream) {
  if (chunk.choices[0].delta.content) {
    process.stdout.write(chunk.choices[0].delta.content);
  }
}

// Text completions
const textResponse = await client.completions.create({
  model: "gpt-4o-mini",
  prompt: "Hello",
});

// List models
const models = await client.models.list();

// List providers
const providers = await client.providers.list("gpt-4o-mini");

Getting Started

Lunar SDK

Pricing

API Reference

Base URL

Authentication

POST /v1/chat/completions

POST /v1/completions

POST /v1/router

GET /v1/router/profiles

GET /v1/providers

Response Objects

Usage

Error Response

Rate Limits

SDK Usage

Getting Started

Lunar SDK

Pricing

​Base URL

​Authentication

​POST /v1/chat/completions

​POST /v1/completions

​POST /v1/router

​GET /v1/router/profiles

​GET /v1/providers

​Response Objects

​Usage

​Error Response

​Rate Limits

​SDK Usage

Base URL

Authentication

POST /v1/chat/completions

POST /v1/completions

POST /v1/router

GET /v1/router/profiles

GET /v1/providers

Response Objects

Usage

Error Response

Rate Limits

SDK Usage