Getting started

1. Create a client key

Sign in to the dashboard, open Client keys, and create a key. The full sek_… value is shown once — store it immediately.

2. Call the gateway

curl https://api.simhaonline.ai/v1/chat/completions \
  -H "Authorization: Bearer sek_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Summarise the router architecture."}]
  }'

Model IDs use the provider/model form from /v1/models; unprefixed aliases resolve when the model name is unique across providers.

3. List models

curl https://api.simhaonline.ai/v1/models \
  -H "Authorization: Bearer sek_YOUR_KEY"

The catalog is refreshed every few minutes from every configured account; per-model policies (input/output ceilings, dedupe) are applied automatically.

Rate limits & failover

Each provider account has rolling minute/day/week ceilings enforced before dispatch. When an account hits a provider throttle it enters a cooldown with exponential strikes; your request transparently fails over to the next healthy account. Nothing is double-billed: failed dispatches are not recorded as usage.

4. Plans & billing (Stripe)

Every account starts on Free (200 requests/day, 3,000/month, 1 API key). Pro ($19/mo) raises this to 5,000/day and 80,000/month with 5 keys; Business ($99/mo) is unlimited with 20 keys. Paid plans are billed through Stripe Checkout — pick a plan on the pricing page, pay by card, and the higher limits apply immediately (the gateway enforces them per request). Manage your card, invoices or cancellation anytime via Manage billing in the dashboard, which opens the Stripe customer portal. Over-limit API calls return 429 with an upgrade hint.

5. API reference

POST /v1/chat/completions — OpenAI-compatible chat. Body: model, messages, optional stream, temperature, max_tokens, tools.

GET /v1/models — list the catalog. Unauthenticated callers receive a sample with total_models; a valid key returns everything.

POST /v1/embeddings — vector embeddings for routed models that support them (same model/input shape as OpenAI).

Headers — Authorization: Bearer sek_… (required), X-Simha-Routing-Mode: quality|fast|cost (optional), X-Request-ID (propagated for tracing).

Streaming — set "stream": true to receive Server-Sent Events in OpenAI chunk format; failover happens before the first chunk, never mid-stream.

Compare mode — header X-Simha-Mode: compare runs the request against up to 3 models, judges the responses, and returns the synthesis with per-model scores.

6. Error codes

401 — missing/invalid key. 403 — account not verified. 404 model_not_found — unknown model slug (check /v1/models). 429 upstream_capacity — every account for the model is cooling down or at capacity; honor Retry-After. 429 (login) — too many attempts, account temporarily locked. 5xx — upstream/provider problems, always retryable.

7. SDK examples

Node.js / TypeScript — the official openai npm package works unchanged:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.simhaonline.ai/v1',
  apiKey: process.env.SIMHA_API_KEY,
});

const stream = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-4',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

Python — same shape as the quickstart above; add stream=True for SSE.

Key rotation — create a new key in the dashboard, switch your app, then delete the old one. Keys are shown once at creation.

8. Failover behavior

Routing order: capability match → health (cooldowns/strikes) → routing mode (best quality / fastest / lowest cost) → round-robin within equals. Provider 429/5xx triggers strike-based cooldown and instant failover; provider 402 (credit exhausted) circuit-breaks the account for up to an hour. Unknown models return404 model_not_found instead of wasting a retry.