> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.

# Connect a client to Model Gateway

> Get an API key, point the OpenAI or Anthropic SDK at Atlan Model Gateway, and make your first governed model call.

Model Gateway speaks the OpenAI and Anthropic APIs. Any client built on
either one moves to the gateway by changing two values: the base URL and the
API key. Every call is then priced, counted against your budget, and visible
in the Model Gateway studio.

## Before you begin

* An Atlan account with access to the workspace you will work in.
* A client or SDK that speaks the OpenAI or Anthropic API.
* The gateway base URLs:

  | Dialect | Base URL |
  | - | - |
  | OpenAI | `https://api.atlan.com/openai/v1` |
  | Anthropic | `https://api.atlan.com/anthropic/v1` |

## Get an API key

<Steps>
  <Step title="Create an agent">
    Open the [Model Gateway studio](https://api.atlan.com/model/v1/ui/), go
    to **Agent access**, and select **Create agent**. Enter a name, and for
    **Workspace** pick your personal workspace, the one with your name.
    Anyone can create an agent there. Creating one in a shared workspace
    takes admin on that workspace.
  </Step>

  <Step title="Copy the key">
    The API key is shown once, when the agent is created. Store it in your
    secret manager or shell environment as `ATLAN_API_KEY`. Never commit it
    to a repository. If you lose it, select **Rotate key** on the agent's row
    to get a new one.
  </Step>
</Steps>

## List the models you can call

```bash theme={null}
curl https://api.atlan.com/openai/v1/models \
  -H "Authorization: Bearer $ATLAN_API_KEY"
```

The response lists every model you can route to, in OpenAI's format. Each
entry has an `id` and a `modality`, such as `chat` or `embedding`. Use the
`id` of a `chat` model, for example `global.anthropic.claude-haiku-5-5`, as
the `model` in the calls below.

## Make your first call

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.atlan.com/openai/v1/chat/completions \
      -H "Authorization: Bearer $ATLAN_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model": "<model-id>",
           "messages": [{"role": "user", "content": "Hello"}]}'
    ```
  </Tab>

  <Tab title="OpenAI SDK (Python)">
    ```python theme={null}
    import os

    from openai import OpenAI

    client = OpenAI(
        base_url="https://api.atlan.com/openai/v1",
        api_key=os.environ["ATLAN_API_KEY"],
    )
    reply = client.chat.completions.create(
        model="<model-id>",
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(reply.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Anthropic SDK (Python)">
    The Anthropic SDK appends `/v1/messages` itself, so its base URL stops
    at `/anthropic`.

    ```python theme={null}
    import os

    from anthropic import Anthropic

    client = Anthropic(
        base_url="https://api.atlan.com/anthropic",
        api_key=os.environ["ATLAN_API_KEY"],
    )
    reply = client.messages.create(
        model="<model-id>",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}],
    )
    print(reply.content[0].text)
    ```
  </Tab>

  <Tab title="Claude Code">
    Point Claude Code at the Anthropic base URL, and name gateway model IDs
    for both its main model and its fast background model:

    ```bash theme={null}
    export ANTHROPIC_BASE_URL="https://api.atlan.com/anthropic"
    export ANTHROPIC_AUTH_TOKEN="$ATLAN_API_KEY"
    export ANTHROPIC_MODEL="global.anthropic.claude-sonnet-5-5"
    export ANTHROPIC_DEFAULT_HAIKU_MODEL="global.anthropic.claude-haiku-5-5"
    claude
    ```

    Use any Claude `id` from `GET /models` for either variable.
  </Tab>

  <Tab title="Codex">
    Add the gateway as a model provider in `~/.codex/config.toml`:

    ```toml theme={null}
    model = "global.anthropic.claude-sonnet-5-5"
    model_provider = "atlan"
    web_search = "disabled"

    [model_providers.atlan]
    name = "Atlan Model Gateway"
    base_url = "https://api.atlan.com/openai/v1"
    env_key = "ATLAN_API_KEY"
    wire_api = "responses"
    ```

    Then run `codex` with `ATLAN_API_KEY` set. Use any chat `id` from
    `GET /models` as `model`. Turn off Codex's built-in web search, as
    above: the gateway does not run hosted tools.
  </Tab>
</Tabs>

The OpenAI dialect reaches every chat model, including Claude. Use the
Anthropic dialect for Claude models.

## Supported operations

| Operation | Path | Notes |
| - | - | - |
| Chat completions | `POST /openai/v1/chat/completions` | Unary and streaming |
| Messages | `POST /anthropic/v1/messages` | Unary and streaming |
| Responses | `POST /openai/v1/responses` | Stateless only. Retrieve, delete, and cancel are not served. |
| Legacy completions | `POST /openai/v1/completions` | Answered by a chat model |
| Embeddings | `POST /openai/v1/embeddings` | |
| List models | `GET /openai/v1/models` | |
| Images, speech, transcription, moderation, rerank | `/openai/v1/...` | Same paths as the OpenAI API |

Batches, assistants, vector stores, fine-tuning, and Anthropic's token
counting are not served and return `404`. On the Anthropic dialect,
`metadata` is accepted and ignored, and a `context_management` that edits the
conversation is refused with `400`.

## Expected result

The call returns a model reply. Its tokens and cost are metered to the agent
whose key made it.

## Troubleshooting

| Symptom | Cause and fix |
| - | - |
| `401` | The key is missing, mistyped, or revoked. Check that `ATLAN_API_KEY` is set in the shell that runs the client. |
| `404` with `not_found` | The `model` is not one you can route to, or the operation is not served. Copy the `id` exactly from `GET /models`, and check [Supported operations](#supported-operations). |
| `400` with `invalid_request` | The request does not fit the model, such as an embedding model on chat completions, or it uses a field the gateway refuses. Check the model's `modality` in `GET /models`, and the fields under [Supported operations](#supported-operations). |
| `503` with `service_unavailable` | The model's provider is unavailable. Retry later, or pick a model from another provider. |
| `429` | A budget or rate limit refused the call. The error names the limit that refused it. Ask your admin to raise it, or wait for the window to reset. |
| A model is missing from `GET /models` | Its provider or the model is disabled, or it is not in your workspace. Ask your admin to enable it. |

## Next steps

<CardGroup cols={2}>
  <Card title="MCP Gateway" icon="network-wired" href="/gateway/mcp/index">
    Give the same agents governed access to tools.
  </Card>

  <Card title="AI Gateway overview" icon="tower-broadcast" href="/gateway/index">
    See how the gateways fit together.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.