> ## 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 `aireg` CLI; `aireg --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 AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces. # How Model Gateway works > Follow a model request through Model Gateway: authentication, model resolution, dialect translation, the provider call, and the usage record. Model Gateway is a proxy between your code and your model providers. It accepts a request in the OpenAI or Anthropic format, finds the model you named, sends the request to that model's provider, and returns the reply in the format you called with. ```mermaid theme={null} sequenceDiagram participant C as Your client participant G as Model Gateway participant P as Provider C->>G: Request with Atlan key and model "/" G->>G: 1. Authenticate the caller G->>G: 2. Resolve the model name G->>G: 3. Check the request fits the model G->>G: 4. Choose the provider API and translate G->>P: 5. Call with the provider credential P-->>G: Reply and token usage G-->>C: Reply in your dialect, with x-gateway-model-wire G->>G: 6. Record usage for the call ``` ## Request lifecycle | Step | What the gateway does | What you see if it fails | | - | - | - | | 1. Authenticate | Reads your Atlan key from `Authorization: Bearer`. On the Anthropic dialect it also reads `x-api-key`; if both are sent, they must match. | `401` | | 2. Resolve the model | Looks up the `/` name you sent, as you, in your workspace first and then the organization's default workspace. The model and its provider must both be on. | `404` with `model not found` | | 3. Check the request | Confirms the model's modality matches the endpoint and the model supports what you sent, such as images, documents, tools, or streaming. | `400`, for example `model is not a chat model.` | | 4. Translate | Picks the provider API to call and maps your request onto it. | `400` naming the field it can't carry | | 5. Call the provider | Uses the provider credential stored in Atlan. Retries and fallback follow the model's [Route and fall back across deployments](/gateway/model/how-tos/routing-and-fallback). | `503` when the provider can't be reached | | 6. Record usage | Writes one usage record for the call: who made it, the model and provider, tokens, cost, and timing. | — | Every refusal in steps 1 to 4 happens before the gateway reads a provider credential or calls the provider. ## Providers and model names A provider is a connection an organization admin added, such as your OpenAI organization or one AWS Bedrock region. A model is one entry served through that connection. You call a model by its qualified name: ```text theme={null} / ``` The provider part is the provider's name, a lowercase slug of its display name such as `openai`, or `openai-2` for a second OpenAI connection. The same upstream model behind two providers therefore has two names, and you choose which connection serves the call. A bare upstream id such as the vendor's model name alone resolves nothing. Copy the exact `id` from the catalog: ```bash theme={null} curl https://api.atlan.com/openai/v1/models \ -H "Authorization: Bearer $ATLAN_API_KEY" ``` Each entry has an `id`, a `modality`, and `is_routable`. The list holds only models whose provider is on and that you can call. Add `?modality=embedding` to list one modality, or `?is_provider_disabled_included=true` to also list models behind a switched-off provider, each with `is_routable: false`. To check one name without making a call, use `GET /openai/v1/models//`. ### Which workspace a name resolves in The gateway looks for the name in your workspace first, then in the organization's default workspace, where new providers are added. Your workspace comes from the `X-Atlan-Workspace-Id` header when you send one, otherwise from your credential. The header only chooses where to look: a workspace you can't read adds nothing. ## Modalities Each model has one modality, and only the matching endpoint serves it. Calling a model on the wrong endpoint returns `400` before anything reaches the provider. | Modality | Served by | | - | - | | `chat` | `/chat/completions`, `/responses`, `/completions` on `/openai/v1`, and `/messages` on `/anthropic/v1` | | `embedding` | `/embeddings` | | `classifier` | `/decisions` | | `image_generation` | `/images/generations`, `/images/edits`, `/images/variations` | | `audio_speech` | `/audio/speech` | | `audio_transcription` | `/audio/transcriptions` | | `realtime` | `/realtime` (WebSocket) | | `rerank` | `/rerank` | | `moderation` | `/moderations` | | `video_generation` | None. These models are listed in the catalog but every endpoint refuses them. | Beyond modality, each model carries a record of what it can take: input types, tools, streaming, structured output, and context and output ceilings. A request that needs more than the record allows is refused with `400` naming what is missing, such as `deployment does not support image input`. ## Translation between dialects You can call any chat model from either dialect. The gateway calls the provider's own API for your dialect when the provider has one, and translates your request onto another API the provider serves when it doesn't. For example, an Anthropic SDK call to a model on Bedrock goes out on Bedrock's API, and the reply comes back in Anthropic's format. Each request field is handled by what it means: | A field that… | Is | | - | - | | Has an equivalent on the provider's API | Mapped to it, such as OpenAI `user` to Anthropic `metadata.user_id` | | Only tunes or annotates the request, such as `metadata`, `context_management`, or `seed` | Dropped, and named in `x-gateway-model-dropped` | | Changes what the reply contains, such as `logprobs` or `logit_bias` | Refused with `400`, naming the field | The model's family also shapes the request. The gateway fills a default the provider requires, such as `max_tokens` of 4096 on the Messages API, and drops a field the model forbids when it is sent at its default value. A value the model can't accept is refused with `400 model_request_unsupported`, naming the field. Two response headers on chat replies tell you what happened: | Header | Meaning | | - | - | | `x-gateway-model-wire` | The provider API the request went out on: `chat_completions`, `responses`, `messages`, `converse`, `invoke_model_messages`, `raw_predict`, or `generate_content`. | | `x-gateway-model-dropped` | Comma-separated request fields that API had no slot for, dropped rather than refused. Absent when nothing was dropped. | Tool definitions, tool calls, and tool results cross dialects with their call IDs intact. Your application runs the tools; the gateway does not. ## What the gateway keeps | Kept | Not kept | | - | - | | The provider and model catalog, with each model's version history | Your prompts and the model's replies | | Provider credentials, stored as secrets that the provider references | Conversation state: the Responses API is stateless, and `store` is never forwarded | | One usage record per call: who, which agent, workspace, model, provider, tokens, cost, duration, and time to first token | Provider response bodies in error messages | The one exception to "not kept" is the [Cache identical responses](/gateway/model/how-tos/cache-responses). It is off by default. When an admin turns it on for a model, the gateway keeps that model's replies for the time set, keyed by a digest of the request. ## Related * [Connect client to Model Gateway](/gateway/model/how-tos/connect-a-client): make a first request. * [Model API compatibility](/gateway/model/references/compatibility): endpoints, headers, and field support. * [Route and fall back across deployments](/gateway/model/how-tos/routing-and-fallback): what step 5 does when a provider fails. * [Review model usage](/gateway/model/how-tos/review-usage): find the usage record from step 6. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.