Proxy API

The Arcana Proxy lets you route LLM API requests through Arcana's infrastructure for unified billing, caching, rate limiting, and usage analytics. It's compatible with the OpenAI SDK — just change the base URL and API key.

Quick Start

Replace your OpenAI client configuration with the Arcana proxy URL and your Arcana session token:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://proxy-arcana.otnelhq.com/v1",
  apiKey: "arc-session-token",  // Your Arcana session token
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

Authentication

Authenticate by passing your Arcana session token as the API key. You can get your session token from the Arcana CLI:

# Copy your session token
arcana session token

The token is sent via the Authorization: Bearer header or the apiKey field in the OpenAI SDK.

API Endpoints

Chat Completions

POST https://proxy-arcana.otnelhq.com/v1/chat/completions

Send a chat completion request. The endpoint accepts the same request body as the OpenAI Chat Completions API.

curl https://proxy-arcana.otnelhq.com/v1/chat/completions \
  -H "Authorization: Bearer $(arcana session token)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "messages": [{"role": "user", "content": "Explain quantum computing"}],
    "stream": true
  }'

List Models

GET https://proxy-arcana.otnelhq.com/v1/models

Returns available models and their providers:

curl https://proxy-arcana.otnelhq.com/v1/models \
  -H "Authorization: Bearer $(arcana session token)"

Balance & Usage

GET https://proxy-arcana.otnelhq.com/v1/balance
GET https://proxy-arcana.otnelhq.com/v1/usage

Check your proxy credit balance and daily usage:

curl https://proxy-arcana.otnelhq.com/v1/balance \
  -H "Authorization: Bearer $(arcana session token)"

curl https://proxy-arcana.otnelhq.com/v1/usage \
  -H "Authorization: Bearer $(arcana session token)"

Health Check

GET https://proxy-arcana.otnelhq.com/v1/health

Returns proxy status and account tier information:

curl https://proxy-arcana.otnelhq.com/v1/health \
  -H "Authorization: Bearer $(arcana session token)"

# Response
{
  "status": "ok",
  "tier": "pro",
  "version": "0.3.45"
}

Model Naming Convention

Models are specified using the format provider/model-name. Examples:

Streaming

The proxy supports server-sent events (SSE) streaming. Set stream: true in your request body:

const stream = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Write a poem" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Rate Limits

Rate limits depend on your account tier:

Rate limit headers are returned in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1623456789