Reference

API endpoints

The gateway speaks the OpenAI HTTP format. Paths below are relative to your base URL, which ends in /v1.

Early accessBy invitationLast updated 5 October 2026

Base URL and auth

Every request carries your virtual key as a bearer token:

http

POST https://YOUR-GATEWAY-HOST/v1/chat/completions
Authorization: Bearer YOUR_VIRTUAL_KEY
Content-Type: application/json

Only inference routes are open to app keys. Administration is not reachable with an app key, and there is no web console for invited teams.

Routes

Routes open to app keys
Method	Path	What it does
POST	`/chat/completions`	Chat, streaming, tool calls and JSON output
POST	`/completions`	Older text-completion format
POST	`/responses`	OpenAI Responses format
POST	`/embeddings`	Text embeddings
POST	`/rerank`	Rank documents against a query, with `askshiva-rerank` (Cohere-style body)
POST	`/images/generations`	Generate an image, with `askshiva-image`
POST	`/images/edits`	Edit an image
POST	`/audio/transcriptions`	Speech to text, with `askshiva-stt`
POST	`/audio/speech`	Text to speech, with `askshiva-tts` or `askshiva-tts-local`
POST	`/moderations`	Moderation check
GET	`/models`	The names your key may call (and nothing else)
POST	`/messages`	Anthropic Messages format
POST	`/messages/count_tokens`	Token count for a Messages request

What we have tested

On 4 October 2026 we checked chat (plain, streaming, tool calls and strict JSON), embeddings, image generation, speech in both directions, and the model list, end to end. The other routes are open but less exercised: tell us if your app depends on one.

Use GET /models rather than GET /models/{id}: the single-model route is not open to app keys.

Errors

What the gateway can answer besides 200
Status	Meaning	What to do
401	The key is missing, wrong or retired	Send `Authorization: Bearer <key>`. If the key was replaced, use the new one.
403	The model is not on your key’s list	Call `GET /models` to see your list. Ask us if you need another alias.
429	Your key hit its requests-per-minute, tokens-per-minute or parallel-request limit	Back off and retry. Honour `Retry-After` when it is sent.
Budget error	Your key has used its budget for the current 30-day period	Calls are refused until the period resets or the budget is raised. The message says the budget is exceeded.
400	The request itself is invalid	Not retried by the gateway. Fix the request.
5xx or timeout	Every model in the alias’s chain failed or timed out	Retry later, or use your own fallback. See fallbacks.

Some error bodies, for example after a timeout, list model names from the gateway’s fallback table. Treat them as diagnostic detail, not as a contract: they change.

Without an SDK

Any HTTP client works. Here is the same call with fetch, including a basic 429 back-off.

javascript

// Plain fetch, no SDK (server-side)
const res = await fetch(`${process.env.ASKSHIVA_BASE_URL}/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ASKSHIVA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "askshiva-fast",
    messages: [{ role: "user", content: "Hello" }],
  }),
});
if (res.status === 429) {
  const wait = Number(res.headers.get("retry-after") ?? "1");
  // back off for `wait` seconds, then retry
} else if (!res.ok) {
  throw new Error(`Gateway answered ${res.status}: ${await res.text()}`);
}
const data = await res.json();