# Providers and models

A **provider** is an AI service ATLAS can call on your behalf. A **model** is a named, priced way of using one model on that provider. Together they define what your people and tools can use.

## Building blocks

```mermaid
flowchart LR
  Cat[Model catalogue] -. optional link .-> M
  P[Provider<br/>address, credentials, policy] --> M[Model<br/>name, slug, protocol, prices]
  M --> Ref[Model reference<br/>provider-slug/model-slug]
  Ref --> GW[Request to the gateway]
  GW --> P
```

- **Provider.** Where to connect and how to authenticate. It belongs to your organisation, or ilionx provides it and shares it with every organisation as read-only.
- **Model.** One model on one provider. It can't move to another provider.
- **Catalogue.** Reference information about well-known models: capabilities, limits and list prices. Linking a model to the catalogue is optional. ATLAS never links a model automatically. It suggests matches that you accept or ignore.

## Provider types

A provider type is a preset for how to connect. It isn't a vendor. Mistral, Groq, DeepSeek and your own vLLM server all use the OpenAI-compatible type with a different address.

| Type                        | Use it for                                                    |
| --------------------------- | ------------------------------------------------------------- |
| OpenAI Compatible           | OpenAI and any service that speaks the OpenAI API             |
| Azure (OpenAI / AI Foundry) | Models deployed in your Azure subscription                    |
| Anthropic Compatible        | Anthropic, and services that speak the Anthropic Messages API |
| Ollama Compatible           | Models served by Ollama                                       |
| AWS Bedrock                 | Models available through Amazon Bedrock                       |

One provider can host models that speak different request formats, as long as the format suits the provider. For example, Claude on an Azure or Bedrock provider uses the Anthropic format. Other models there use the provider's default. What you can save is exactly what the gateway can route.

## Credentials

ATLAS stores credentials encrypted and write-only. Once you save them, ATLAS tells you only whether they're configured. The kind of credential depends on the provider:

| Provider                            | Credential                                                         |
| ----------------------------------- | ------------------------------------------------------------------ |
| OpenAI Compatible, Azure, Anthropic | API key                                                            |
| Ollama                              | None                                                               |
| AWS Bedrock                         | A Bedrock API key, or IAM access keys (optionally assuming a role) |

## Testing a connection

After you save a provider, ATLAS tests it in the background. Saving never waits for the test, so a slow or unavailable provider can't stop you editing it. If the test fails, you get a warning that says what to fix:

- The address is unreachable.
- The credentials were rejected.
- The address isn't an AI service.
- For Bedrock, the role can't be assumed or the region is unreachable.

Tests are free. They ask the provider for its model list instead of running a real request. They check that the provider is reachable and your credentials work. They can't tell whether you chose the wrong format or misspelled a model name. That shows up on the first real request. ATLAS also monitors the availability of your enabled providers.

## Getting models in

You can add models in three ways. Each way fills in only the fields you haven't already filled in:

```mermaid
flowchart TD
  D[Discovery<br/>ask the provider what it serves] --> Match{Match to catalogue}
  Match -->|exact| C[Confirmed]
  Match -->|one near match| S[Suggested<br/>you accept or ignore it]
  Match -->|none or ambiguous| U[Unmatched]
  Cat[Catalogue picker] --> F[Pre-filled form]
  Man[Manual entry] --> F
  C --> F
  S -->|you accept| F
  U --> F
  F --> Price[Review pricing]
  Price --> Save[Save model]
```

- **Discovery** asks the provider what it really serves, such as your Azure deployments or Ollama models.
- **Catalogue** lists a vendor's published models. Use it when a provider can't list its own.
- **Manual** needs only the deployed model name.

ATLAS never takes prices silently. Catalogue list prices pre-fill the form, but you must confirm them on the pricing step. A model with no price costs nothing and counts for nothing against budgets, so the model list warns you about it. When you add several models at once, you review each one's pricing before saving.

## Model references

Callers name a model as `provider-slug/model-slug`. Changing a model's display name changes nothing for callers. Editing a slug breaks existing references, and the app warns you before you do. ATLAS doesn't accept a bare model name, because two providers can each have a model with the same name. The provider never sees the reference. It receives the deployed model name.

## What a model can do

Each model declares which kinds of work it offers: chat, embeddings, rerank, transcription or speech. The gateway checks this before it calls the provider. If you ask a chat-only model for embeddings, the gateway refuses immediately.

## Request parameters

ATLAS forwards the extra parameters your tools send, so provider-specific features work without waiting for a release. ATLAS itself controls a few fields, such as the model, the messages and token limits. If a client value collides with one of those, ATLAS drops it and tells the caller which parameters it dropped. Stored model defaults apply only when the caller doesn't send a value. A value from the caller always wins.

Each provider also has a parameter policy that Admins can tune. ATLAS may remove parameters a model doesn't support. For more information, see [Gateway](https://docs.atlas.ilionx.dev/concepts/gateway.md#unknown-parameters) and [Tune how a provider handles request parameters](https://docs.atlas.ilionx.dev/guides/admin/gateway-tune-provider-parameter-handling.md).

## Provided by ilionx and your own

ilionx manages the providers and models it provides. They appear in every organisation's lists with a **Platform** badge, read-only. You can block them in a space or add them to a project exactly like your own models. An organisation model may share a name with a platform model. The list flags it, and the provider slug in the reference keeps the two apart.

## Deleting

ATLAS refuses to delete a provider that still has models, unless you confirm that its models should be deleted too. That also removes them from any project model lists.

## Related

- Concepts: [Gateway](https://docs.atlas.ilionx.dev/concepts/gateway.md), [Budget and cost](https://docs.atlas.ilionx.dev/concepts/budget-and-cost.md), [Spaces](https://docs.atlas.ilionx.dev/concepts/spaces.md), [Projects](https://docs.atlas.ilionx.dev/concepts/projects.md)
- Guides: [Add an AI provider](https://docs.atlas.ilionx.dev/guides/admin/providers-and-models-add-provider.md), [Add models to a provider](https://docs.atlas.ilionx.dev/guides/admin/providers-and-models-add-models.md)