Connect an OpenAI- or Anthropic-compatible client#

Point any tool or SDK that speaks the OpenAI or Anthropic API at the ATLAS gateway, and fix the errors you're most likely to meet. Every other connection guide links here for the shared settings.

If you use Claude Code or opencode, the web app can generate the configuration for you. See Connect Claude Code and opencode. For IDEs, see Connect your IDE.

Before you begin#

You need an ATLAS API key that has an acting context (a space or project). See Create and manage your API keys.
You need at least one model in the key's space or project. The Anthropic endpoint needs a Claude model.
You need your ATLAS address. Replace https://<atlas-host> with it throughout. Ask an Admin if you're unsure.
Replace <your-atlas-key> with your own key.

Connection settings#

Setting	OpenAI-compatible	Anthropic-compatible
Base URL	`https://<atlas-host>/gateway/openai/v1`	`https://<atlas-host>/gateway/anthropic`
Authentication	`Authorization: Bearer <your-atlas-key>`	`Authorization: Bearer <your-atlas-key>` or `x-api-key: <your-atlas-key>`
Model	`provider-slug/model-slug`	`provider-slug/model-slug`
Main endpoint	`POST /chat/completions`	`POST /v1/messages`

The /gateway path segment is part of every URL. Without it every request returns 404.
A model reference always has both parts, for example openai/gpt-4.1. A bare name such as gpt-4.1 is rejected with 404 model_not_found. Copy references from the /models request in step 3 of Connect an OpenAI-compatible client instead of typing them.
The OpenAI namespace also offers /models, /responses, /embeddings, /rerank, /audio/transcriptions and /audio/speech. It has no legacy /completions endpoint, so tools that need fill-in-the-middle autocomplete can't use it.
Send one authentication header only. If you send Authorization and x-api-key with different keys, the gateway refuses the request with 401.

Connect an OpenAI-compatible client#

Set the client's base URL to https://<atlas-host>/gateway/openai/v1.
Set its API key to your ATLAS API key. The client sends it as Authorization: Bearer.
List the models your key can use and copy the id of one:
bash
```
curl -s https://<atlas-host>/gateway/openai/v1/models \
  -H "Authorization: Bearer <your-atlas-key>"
```
Add ?endpoint=embeddings (or chat, rerank, transcription, speech) to list only the models for that purpose.

Send a test request:

bash

curl -s https://<atlas-host>/gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer <your-atlas-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4.1","messages":[{"role":"user","content":"Hello"}]}'

The response is a JSON completion without an error object.

ATLAS removes parameters the target model doesn't support, and the provider's parameter policy and rules can remove more. When ATLAS removes anything, the response lists the parameters in an atlas_stripped_parameters array. For more information, see Gateway: unknown parameters.

Connect an Anthropic-compatible client#

Set the environment, or the equivalent settings in your SDK:
bash
```
export ANTHROPIC_BASE_URL="https://<atlas-host>/gateway/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-atlas-key>"
```
ANTHROPIC_API_KEY works instead of ANTHROPIC_AUTH_TOKEN. The client then sends the key as x-api-key. Don't set both to different keys.
Use ATLAS model references (provider-slug/model-slug) as the model names. They must be Claude models.
Start the tool and send a request.

Requests, token usage and cost appear in the audit log and in My usage. ATLAS attributes them to your key's space or project.

Check the connection#

Before you debug a tool, check the key and model from a terminal. The /models request in step 3 of Connect an OpenAI-compatible client returns JSON.

Troubleshooting#

Symptom	Cause and remedy	Code
Authentication fails	The key is missing, mistyped, expired, revoked or conflicts with a second key. The gateway doesn't say which. Check that the tool sends `Authorization: Bearer`, and that on the OpenAI base URL it does not use `x-api-key` or `api-key`.	`401 authentication_required`
Model not found	The reference is wrong, the model is inactive, or your space or project does not offer it. Copy it from `/models`, and check that the tool keeps the `/` in the base URL path.	`404 model_not_found`
The key has no context	The key has no acting context. Use Switch Context on the key.	`403 no_acting_context`

For every other gateway error, including budget and provider errors, in both the OpenAI and the Anthropic format, see the errors reference.