Model router API reference

This reference lists the exact endpoints, headers, request and response fields, errors, and resource properties for model router in Microsoft Foundry. Use it to look up an identifier quickly. For step-by-step guidance, follow the links in each section.

  • Set model to auto for Auto (model router without a deployment, preview), or to your model router deployment name.
  • Responses and Chat Completions use the /openai/v1/ path, and Messages uses /anthropic/v1/. No api-version query parameter is needed.
  • Per-request controls, session affinity, and routing metadata (preview) require the Foundry-Features: ModelRouterControls=V1Preview header.
  • The model field in every response names the model that answered.

Important

Features or capabilities marked (preview) in this article are in public preview and are subject to the Supplemental Terms of Use for Microsoft Azure Previews. Previews are provided without a service-level agreement, and Microsoft doesn't recommend them for production workloads. Certain features might not be supported or might have constrained capabilities.

Endpoints

API Resource endpoint Project endpoint
Responses https://<resource>.services.ai.azure.com/openai/v1/responses https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/responses
Chat Completions https://<resource>.services.ai.azure.com/openai/v1/chat/completions https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/chat/completions
Messages (preview) https://<resource>.services.ai.azure.com/anthropic/v1/messages Not available
  • All five endpoints accept Auto and model router deployments.
  • The https://<resource>.openai.azure.com/openai/v1/ host also works for Responses and Chat Completions.
  • Only Claude models answer Messages requests, and each one must be deployed in the same Foundry resource.

For guidance, see Choose an endpoint.

Authentication

Setting Responses and Chat Completions Messages (preview)
API key header api-key: <key> or Authorization: Bearer <key> x-api-key: <key>. Sending api-key instead of x-api-key returns HTTP 401.
Microsoft Entra ID header Authorization: Bearer <token> Authorization: Bearer <token>
Token scope https://ai.azure.com/.default https://ai.azure.com/.default
Role for Microsoft Entra ID Foundry User on the resource or project Foundry User on the resource or project

For code samples, see Authenticate. For roles, see Role-based access control for Microsoft Foundry.

Request fields

Field Type API Description
model string All auto for Auto, or your model router deployment name. model-router also works for Auto when your resource has no deployment with that name. If your resource has a deployment named auto, requests with model set to auto go to that deployment.
max_tokens integer Messages Required.
previous_response_id string Responses Continues a conversation. Model router considers the earlier turns when it ranks models, and uses the ID to identify the conversation for session affinity.
conversation string or object Responses Continues a conversation. Model router considers the earlier turns when it ranks models, and uses the conversation ID to identify the conversation for session affinity.
routing_config (preview) object All Per-request controls. Requires the Foundry-Features: ModelRouterControls=V1Preview header. Without the header, model router ignores the object.
routing_config.mode string All balanced, quality, or cost (case-insensitive). Overrides the routing mode for this request.
routing_config.models array of strings All Model names without versions, for example ["gpt-5.6-sol", "claude-sonnet-5"]. Case-insensitive; duplicates are ignored; must be non-empty. Routes only across these models for this request, and one model pins the request to that model. Narrows routing only: listed models that the deployment's model subset or Auto's model list doesn't include are ignored, and HTTP 400 is returned if none remain. With require_parameters set to true, any such model returns HTTP 400. Claude models need a deployment in your resource.
routing_config.require_parameters boolean All false (default) or true. When true, only models that support every parameter you sent are eligible. If none qualify, the request fails with HTTP 400, and no model is called.
routing_config.session_affinity object All Session affinity for this request.
routing_config.session_affinity.strategy string All adaptive (the default when you send the header), sticky, or none. The older field name mode is still accepted.
routing_config.session_affinity.session_id string All Identifies a conversation for session affinity. 1–256 characters, and not only whitespace. Mustn't contain secrets or personal data. Model router ignores an invalid value and doesn't return the ID in the response.

Send reasoning effort in each API's native field. routing_config has no reasoning-effort field.

API Reasoning effort field
Chat Completions reasoning_effort
Responses reasoning.effort
Messages output_config.effort

By default, model router drops optional parameters that the selected model doesn't support, such as temperature, top_p, presence_penalty, frequency_penalty, logit_bias, logprobs, and stop on reasoning models, or a reasoning effort on non-reasoning models. With routing_config.require_parameters set to true, the request fails with HTTP 400 instead. For details, see How model router handles parameters and Control model router routing per request.

Request headers

Header API Value Description
Foundry-Features All ModelRouterControls=V1Preview Preview. Turns on per-request controls, session affinity (adaptive by default), and routing metadata in the response. Without it, model router ignores routing_config and routes each request independently.
x-ms-session-id All A session ID of 1–256 characters Preview. Identifies a conversation for session affinity when the body has no valid routing_config.session_affinity.session_id. Mustn't contain secrets or personal data.
api-key Responses, Chat Completions <key> API key. The Messages API doesn't accept it in place of x-api-key (HTTP 401).
Authorization All Bearer <token>, or Bearer <key> for Responses and Chat Completions Microsoft Entra ID token with scope https://ai.azure.com/.default, or an API key.
x-api-key Messages <key> API key for the Messages API.
anthropic-version Messages For example, 2023-06-01 Optional. Defaults to 2023-06-01.
anthropic-beta Messages Anthropic beta feature names Passed through to the selected model. Support depends on the model.

Response fields

Every response includes model. With the Foundry-Features: ModelRouterControls=V1Preview header, responses also include model_selection_details (preview). Its fields are optional during the preview, so parse them defensively and tolerate fields that you don't recognize.

Field Type Description
model string The model that served the request, for example gpt-5.6-luna-2026-07-09.
reasoning.effort string Responses API only. The reasoning effort that an OpenAI reasoning model used. Claude models don't report it.
model_selection_details.model_router_details object Preview. Routing metadata for the request.
model_selection_details.model_router_details.mode string The routing mode used: balanced, quality, or cost.
model_selection_details.model_router_details.routing_trace array Ordered routing entries. One entry for Chat Completions. Responses can include one entry per output item.
model_selection_details.model_router_details.routing_trace[].output_id string Responses only. The output item that the entry describes.
model_selection_details.model_router_details.routing_trace[].latency_ms number The latency reported for the entry, in milliseconds.
model_selection_details.model_router_details.routing_trace[].attempts array The ordered model attempts. More than one attempt means that failover happened.
model_selection_details.model_router_details.routing_trace[].attempts[].model string The model attempted, for example gpt-5.6-luna.
model_selection_details.model_router_details.routing_trace[].attempts[].result.status integer The HTTP status of the attempt.
model_selection_details.model_router_details.routing_trace[].attempts[].result.error.code string The error code, when the attempt failed.
model_selection_details.model_router_details.routing_trace[].attempts[].result.error.message string The error message, when the attempt failed.
model_selection_details.model_router_details.session_affinity object The session affinity outcome. Omitted when model router can't look up or save the model association.
model_selection_details.model_router_details.session_affinity.strategy string adaptive, sticky, or none.
model_selection_details.model_router_details.session_affinity.source string Where the conversation identity came from: session_id_payload, session_id_header, derived_fingerprint, or not_available. Omitted when the strategy is none.
model_selection_details.model_router_details.session_affinity.decision string initialize (first turn or new association), retain (same model as the previous turn), or switch (a different model served this turn). Omitted when the strategy is none.

Where the routing metadata appears:

Response Location of model_selection_details
Responses, Chat Completions, or Messages, without streaming The response body
Responses, streaming The response object in the response.completed event
Chat Completions, streaming The final chunk, which has no choices
Messages, streaming The message_delta event

The response doesn't show whether your own deployment or router-managed capacity served the request. The following Chat Completions response, from a later turn of a conversation, shows model and model_selection_details:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1794000000,
  "model": "gpt-5.6-luna-2026-07-09",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Retrieval-augmented generation retrieves relevant passages from your data and adds them to the prompt, so the model can ground its answer in them."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 31,
    "total_tokens": 443
  },
  "model_selection_details": {
    "model_router_details": {
      "mode": "balanced",
      "session_affinity": {
        "strategy": "adaptive",
        "source": "derived_fingerprint",
        "decision": "retain"
      },
      "routing_trace": [
        {
          "latency_ms": 840,
          "attempts": [
            { "model": "gpt-5.6-luna", "result": { "status": 200 } }
          ]
        }
      ]
    }
  }
}

For parsing code, see Get per-request routing details and Check the affinity decision.

Errors

Error API Cause Resolution
HTTP 400, invalid_routing_config All routing_config isn't a JSON object. Send an object, for example { "mode": "cost" }.
HTTP 400, invalid_routing_mode All routing_config.mode isn't balanced, quality, or cost. Use one of the three values.
HTTP 400, invalid_routing_models All routing_config.models isn't a non-empty array of non-empty strings. Send at least one model name, without a version.
HTTP 400, invalid_require_parameters All routing_config.require_parameters isn't a boolean. Send true or false.
HTTP 400, invalid_session_affinity All routing_config.session_affinity isn't an object, or its strategy isn't supported. Send an object with strategy set to adaptive, sticky, or none.
HTTP 400, with a message that no model in the routing pool can preserve all requested parameters All routing_config.require_parameters is true, and no eligible model supports every parameter you sent. No model is called. Remove the unsupported parameter, add models that support it to routing_config.models, or set require_parameters to false.
HTTP 400 All (Auto) Auto is turned off for the resource: properties.instant.modelAllowList doesn't include the model-router entry. Add the model-router entry to modelAllowList, or call your model router deployment. See Turn off Auto.
HTTP 400 Messages No Claude deployment is available to the model router deployment or to Auto. Deploy a Claude model from the pool in the same Foundry resource. See Add Claude models.
HTTP 401 Messages The request sent api-key instead of x-api-key. Send x-api-key or a Microsoft Entra token.
HTTP 429 All The request exceeded the TPM or RPM limit of your model router deployment, or Auto's limit. Retry with exponential backoff, or add capacity. See When you reach the limit.
Insufficient quota available for instant inference All (Auto) All of the subscription's Global Standard model router quota is assigned to deployments. Reduce or delete unused model router deployments, or request more quota. See Quota for Auto.

Without the Foundry-Features header, model router ignores routing_config instead of returning an error. Model router also ignores an invalid session ID instead of returning an error. For more symptoms, see Troubleshoot model router.

Deployment properties

Create or update a model router deployment with the Azure Resource Manager API:

PUT https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource>/deployments/<deployment>?api-version=2025-10-01-preview

Property Values Description
sku.name GlobalStandard, DataZoneStandard The deployment type.
sku.capacity Integer The capacity in units. One unit is 1,000 TPM and 1 RPM. The default when you deploy is 10 units (10,000 TPM).
properties.model.format OpenAI The model format of model router.
properties.model.name model-router The model name of model router.
properties.model.version 2025-11-18 The generally available version and the default for new deployments. The preview versions 2025-08-07 and 2025-05-19 retire on January 27, 2027.
properties.routing.mode balanced (default), quality, cost The deployment's routing mode.
properties.routing.models[] Array of { "format", "name", "version" } objects The model subset. Each entry names a model from the model pool by format, name, and version. Omit it to route across the full pool.
properties.raiPolicyName A content filter (guardrail) name The content filter for all traffic to and from the deployment.

Changes to the routing mode or model subset take up to five minutes to take effect. The following request body deploys model router with the Balanced mode and a three-model subset. The Claude model in the subset needs its own deployment in the same resource.

{
  "sku": { "name": "GlobalStandard", "capacity": 10 },
  "properties": {
    "model": { "format": "OpenAI", "name": "model-router", "version": "2025-11-18" },
    "routing": {
      "mode": "balanced",
      "models": [
        { "format": "OpenAI", "name": "gpt-5.6-sol", "version": "2026-07-09" },
        { "format": "OpenAI", "name": "gpt-5.6-luna", "version": "2026-07-09" },
        { "format": "Anthropic", "name": "claude-sonnet-5", "version": "1" }
      ]
    }
  }
}

For portal, Azure CLI, and Bicep steps, see Deploy model router.

Resource properties for Auto

Auto's settings apply to the whole Foundry resource (account), in properties.instant. Set them with Azure Resource Manager API version 2026-01-15-preview:

  • REST API or az rest: PATCH https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource>?api-version=2026-01-15-preview
  • Bicep: Microsoft.CognitiveServices/accounts@2026-01-15-preview
Property Values Description
properties.instant.routing.mode balanced, quality, cost (case-insensitive) Auto's default routing mode for the resource. Without it, Auto uses the Balanced mode. A request's routing_config.mode overrides it.
properties.instant.routing.models[] Array of { "format", "name", "version" } objects Auto's model subset for the resource. Can't be empty when present. Model router ignores models that aren't available to Auto. A request's routing_config.models can narrow it, but can't add models.
properties.instant.modelAllowList[] Array of { "format", "name", "version" } objects The models that can be called without a deployment (instant access). An empty array ([]) turns off all instant access, including Auto. Outside West US 3, Auto is the only instant-access model. In West US 3, to turn off Auto but keep other instant-access models, leave out { "format": "OpenAI", "name": "model-router", "version": "2025-11-18" }. A new list replaces the old one; it doesn't merge.
properties.instant.raiPolicyName A content filter policy name, for example Microsoft.DefaultV2 The content filter policy for Auto and other instant-access models.

An update to properties.instant resets routing and raiPolicyName when you leave them out, and keeps the current modelAllowList. Each model in modelAllowList must support instant access in the resource's region, or the update fails with HTTP 400. After you set modelAllowList, you can replace it but not remove it.

The properties.instant.routing object has this shape:

{
  "mode": "quality",
  "models": [
    { "format": "OpenAI", "name": "gpt-5.6-sol", "version": "2026-07-09" },
    { "format": "OpenAI", "name": "gpt-6-sol", "version": "2026-09-22" }
  ]
}

For steps, see Configure Auto for your resource and Govern Auto. For instant access in general, see Enterprise controls.

REST API reference