Models and routing

Choose which models each AI system and key may use, share traffic across credentials, and fall back when a provider fails.

Model access

The models each provider credential lists are the models your organization can reach. Within those, owners and admins choose for each key, under Providers and models, which providers and models it may use. Every provider and model lets the key use whatever your credentials allow, including a model name Altrum does not list yet, such as a Bedrock inference profile (bedrock/eu.anthropic.claude-haiku-4-5-20251001-v1:0): the provider answers for it. Turn it off to choose providers one by one, up to 6:

• Allowed models: only these models can be called. * on its own allows every model of the provider; it cannot be combined with other names. A name matches exactly, ignoring case. To match a family of models, write a pattern after regex:, for example regex:gpt-4o.*.
• Blocked models: these models are refused, even when the provider is allowed.

Separate names with commas. Each list holds up to 200 names of up to 200 characters.

A request for a model or provider the key may not use is refused with status 403 and a message that names it:

Code	Message
model_blocked	Model '<model>' is not allowed, followed by the key that refused it
provider_blocked	Provider '<provider>' is not allowed, followed by the key that refused it
provider_blocked	Your organization has no credential for <provider>. Add one under AI Gateway, Provider credentials, or name another provider.

GET /v1/models lists only the models your organization has a credential for and the key may use.

When an owner or a Governance Lead turns on Approved models only in the Model catalog, a model must also be approved, on every key. A model that is not is refused with model_blocked and The model <model> is not approved for this organization. An owner or a Governance Lead can approve it in the Model catalog in Altrum., and GET /v1/models leaves it out.

Share traffic across providers

When a key may use more than one provider, give each a Weight from 0 to 1000 (1 when not set): higher is used more, and first. Weights apply to a request that names a model without a provider, such as gpt-4o-mini: Altrum picks one of the key’s providers that serves that model, in proportion to their weights. A request that names the provider, such as openai/gpt-4o-mini, goes to that provider.

Fallbacks

A request can name other models to try, in order, when the first one fails. Add fallbacks to the request body:

{
  "model": "openai/gpt-4o-mini",
  "messages": [{ "role": "user", "content": "Hello" }],
  "fallbacks": ["anthropic/claude-sonnet-4-5"]
}

Altrum tries each in turn when an attempt returns any error, using your organization’s own credential for each provider. It stops without trying the rest when the request was cancelled, or when a guardrail or a prompt refused it. Guardrails, budgets and rate limits apply to every attempt, and x-alt-fallback-index on the answer says which one answered.

When a request names a model without a provider and sends no fallbacks, the key’s other providers that serve that model are tried, heaviest first.