Gateway reference#

Look up the gateway addresses, authentication, headers, endpoint behaviour and limits. For how the gateway works and why, see Gateway concepts. For error formats, see Errors.

At a glance

• Call OpenAI-style endpoints under https://<atlas-host>/gateway/openai/v1, and Anthropic Messages under https://<atlas-host>/gateway/anthropic.
• Authenticate with an ATLAS API key. The key alone decides the space or project the request runs under. The gateway ignores any space or project header you send.
• Name the model as provider-slug/model-slug, for example openai/gpt-4.1.
• Every request is checked against your model and budget rules before it reaches a provider.

Endpoints#

All paths are relative to https://<atlas-host>/gateway.

Model entry#

Each entry in /openai/v1/models has these fields:

• id, object, created, owned_by
• provider_scope, provider_type, model_name, status
• max_input_tokens, max_tokens, context_length
• endpoints[], top_provider.max_completion_tokens
• A capabilities object with temperature_supported, reasoning, reasoning_options, tool_call, structured_output, context_limit, output_limit, status and modalities

Anthropic model entry#

Each entry has type, id, display_name and created_at. created_at is RFC 3339 in UTC and holds the date the model was added to ATLAS.

Authentication#

A valid key can still be refused. The error tells you why: 403 organization_suspended, project_archived or no_acting_context. See Errors.

Headers#

Your credentials are never forwarded to the provider.

Chat completions#

POST /openai/v1/chat/completions is OpenAI-compatible. model is a reference of the form provider-slug/model-slug. A bare model name returns 404 model_not_found.

• ATLAS understands model, messages, temperature, max_tokens and stream. Other parameters are passed to the provider where the model supports them. See Unsupported parameters.
• max_completion_tokens is accepted. If you send both max_tokens and max_completion_tokens, max_completion_tokens wins and only one limit reaches the provider.
• tools and tool_choice work on OpenAI, Azure OpenAI, Anthropic and Ollama models. See Tool calling.
• Dropped parameters are listed in a top-level atlas_stripped_parameters array, or on the first chunk only when streaming. The array is present only when something was dropped.
• Claude thinking blocks appear as message.reasoning_content (non-streaming) or delta.reasoning_content (streaming).
• content is always present and null when the turn produced no visible text.
• A streamed response never contains an empty "content":"" chunk.

Streaming#

Tokens used before a failure or a client cancel are still counted and billed.

Trailing usage chunk#

Before [DONE], a final chunk with choices: [] carries token usage:

{
  "id": "…",
  "object": "chat.completion.chunk",
  "model": "…",
  "choices": [],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 45,
    "total_tokens": 168,
    "prompt_tokens_details": { "cached_tokens": 80 }
  }
}

Tool calling#

Responses API#

POST /openai/v1/responses accepts the OpenAI Responses format for any chat model. The model decides whether ATLAS passes the request straight to the provider or translates it:

• A model that supports the Responses API natively receives the request unchanged, apart from the model name.
• A chat-only model (Anthropic, Ollama, AWS Bedrock, or any model configured for chat) is served by translating the request to chat and the answer back.
• A chat request to a model configured for Responses is translated the other way.

Embeddings#

POST /openai/v1/embeddings takes {model, input: string | string[], encoding_format?, dimensions?, user?}.

• The gateway accepts a list of any length for every embedding model. If the model limits inputs per upstream call, the gateway splits the list into several calls and runs them in parallel. Cohere Embed models on AWS Bedrock take 96 inputs per call. Amazon Titan Text Embeddings v2 takes one input per call, so a list of 50 inputs makes 50 calls. Other models take the whole list in one call.
• The gateway merges the results in input order. It records one audit entry and one cost for the request, based on the summed input tokens of all calls.
• If any call fails, the whole request fails. Tokens from calls that completed are still billed.
• input_type applies to Cohere Embed models on AWS Bedrock only. Values are search_document (default), search_query, classification or clustering. Any other value returns 400. Other models ignore it.
• With encoding_format: base64, vectors are returned as little-endian 32-bit floats.

Rerank#

POST /openai/v1/rerank needs a rerank model.

Results are sorted by descending score and capped to top_n. The gateway fills in the document text from your request and always returns usage.

Transcription#

POST /openai/v1/audio/transcriptions accepts multipart/form-data and needs a transcription model.

A missing file or model, a duplicate file, an invalid temperature or stream=true returns 400. The provider's answer comes back unchanged with its content type. Audio is never stored.

Speech#

POST /openai/v1/audio/speech needs a speech model.

Audio streams back with the provider's content type. Audio is never stored.

Anthropic Messages#

Claude Code, Anthropic SDKs and opencode use the Anthropic addresses to reach Claude through ATLAS. For client setup, see Connect an OpenAI- or Anthropic-compatible client.

The request body is forwarded as you sent it. Only the model id is replaced.

Model resolution#

The key decides where a model name is looked up.

A model that the space restricts or hides returns 404 model_not_found, the same as a model that does not exist.

Unsupported parameters#

ATLAS removes some parameters a model does not support so the request still succeeds. Removed parameters are listed in atlas_stripped_parameters in the response.

ATLAS does not silently remove parameters that change how you must read the response: n, logprobs, top_logprobs and response_format. On providers that cannot honour them, the request fails with 400 naming the field.

ATLAS adds stored model defaults for any parameter you omitted (JSON null counts as omitted). Your values always win, including none and 0. Admins can adjust parameter handling per provider. See Tune how a provider handles request parameters.

Reasoning parameters#

ATLAS understands these reasoning parameters:

• reasoning_effort (OpenAI, Anthropic, AWS Bedrock)
• reasoning_budget_tokens and reasoning_enabled (Anthropic, AWS Bedrock)

Claude thinking blocks appear as reasoning_content. OpenAI-family models receive reasoning_effort as sent.

Provider failures#

• ATLAS retries temporary provider failures automatically before it returns an error.
• Streams that have already started are not retried.
• A provider may still bill a failed first attempt.
• When a provider keeps failing, you receive one of the errors listed in Errors.
• Your key was valid even if the error mentions the provider's credentials. The problem is on the provider side.
• Quote the atlas-request-id to your ilionx contact.

Budgets#

ATLAS checks budgets before it sends the request. A used-up limit returns 429 budget_exceeded (OpenAI addresses) or 402 with billing_error (Anthropic addresses). For the rules, see Budgets.

Limits#

Related#

• Errors
• API keys
• Budgets
• Glossary
• Reference index