---
title: "Replace an agent's fallback providers"
method: PUT
path: "/api/v1/agents/{agent_id}/fallbacks"
tags: ["agents"]
---

# Replace an agent's fallback providers

`PUT /api/v1/agents/{agent_id}/fallbacks`

## Request

- Base URL: `https://cp.xenovia.io` (the document declares no server; this is the origin it was published from)
- URL: `https://cp.xenovia.io/api/v1/agents/{agent_id}/fallbacks`
- Auth: none declared

Replace the whole ordered list of fallback providers (positions 1..N
in the order sent, at most 3) and, when sent, the failover settings
(``routing``, merged onto the current ones; null resets them).

Each fallback is one of the organisation's provider connections, with an
optional model override. A refused change answers a ``detail`` object
with a stable ``code`` and changes nothing. The agent's config version
(and credential version) advances, so the runtime picks the chain up.

## Path parameters

- `agent_id` string, uuid, required

## Headers

- `Authorization` string, nullable
- `X-Request-ID` string, nullable

## Request body

- AgentFallbacksUpdate: PUT /agents/{agent_id}/fallbacks: the whole ordered list (positions 1..N in this order) and, optionally, routing. Omitting ``routing`` keeps it; null resets it to the defaults.
  - `fallbacks` AgentFallbackEntry[], required
    - `provider_id` string, uuid, required
    - `model` string, nullable
  - `routing` AgentRoutingUpdate: Part or all of AgentRouting; an omitted field keeps its value.
    - `fail_over_on` string[], nullable
    - `attempt_timeout_s` integer, nullable
    - `total_budget_s` integer, nullable
    - `first_token_timeout_s` integer, nullable
    - `breaker_enabled` boolean, nullable
    - `same_residency` boolean, nullable

## Response `200`

Successful Response

- AgentRead
  - `id` string, uuid, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `org_id` string, uuid, required
  - `owner_id` string, uuid, nullable, required
  - `name` string, nullable, required
  - `description` string, nullable, required
  - `system_prompt` string, nullable, required
  - `purpose` string, nullable
  - `purpose_mode` 'monitor' | 'enforce'
  - `status` 'draft' | 'active', required
  - `source` 'auto' | 'manual', required
  - `coding_tool` string, nullable
  - `provider_id` string, uuid, nullable, required
  - `provider` AgentProviderSummary, required
    - `id` string, uuid, required
    - `name` string, required
    - `provider` string, required
    - `model` string, nullable, required
  - `deployment_id` string, uuid, nullable
  - `fallbacks` AgentFallbackRead[]
    - `position` integer, required
    - `provider_id` string, uuid, required
    - `provider` AgentProviderSummary, required
      - `id` string, uuid, required
      - `name` string, required
      - `provider` string, required
      - `model` string, nullable, required
    - `model` string, nullable, required
    - `model_override` string, nullable
    - `residency` 'us' | 'eu' | 'apac' | 'global' | 'unknown'
    - `capabilities` ModelCapabilities: What a model can take, from the public model directory (models.dev); each member is null when the directory does not say (assume capable).
      - `context_window` integer, nullable
      - `max_output` integer, nullable
      - `vision` boolean, nullable
      - `tools` boolean, nullable
      - `reasoning` boolean, nullable
  - `routing` AgentRouting: An agent's failover settings, always whole (every default filled).
    - `fail_over_on` string[]
    - `attempt_timeout_s` integer
    - `total_budget_s` integer
    - `first_token_timeout_s` integer, nullable
    - `breaker_enabled` boolean
    - `same_residency` boolean
  - `primary_capabilities` ModelCapabilities: What a model can take, from the public model directory (models.dev); each member is null when the directory does not say (assume capable).
    - `context_window` integer, nullable
    - `max_output` integer, nullable
    - `vision` boolean, nullable
    - `tools` boolean, nullable
    - `reasoning` boolean, nullable
  - `primary_residency` 'us' | 'eu' | 'apac' | 'global' | 'unknown'
  - `hosted_tools` HostedTools: An agent's hosted tool allow-list: GET/PUT /agents/{agent_id}/hosted-tools, AgentRead.hosted_tools and the config snapshot's ``hosted_tools``. ``mode`` is what the runtime does with a hosted tool outside the list: ``enforce`` refuses the request, ``monitor`` records it and lets it through. ``mcp_servers`` may be set without ``mcp`` in ``families``: it is kept and served, and the runtime allows no MCP tool while ``mcp`` is not in the families (so an admin can switch MCP off without losing the server list).
    - `mode` 'monitor' | 'enforce', required
    - `families` string[]
    - `mcp_servers` HostedMcpServer[]
      - `label` string, required
      - `url` string, nullable
      - `connector_id` string, nullable
      - `tunnel_id` string, nullable
      - `tools` string[]
  - `sub_agents_summary` SubAgentsSummary: AgentRead.sub_agents_summary: how many sub-agents of each kind.
    - `inline` integer
    - `linked` integer
  - `agent_url` string, required: Inference base URL a developer pastes into their client (see format_agent_url for the hybrid/cloud rendering rules).

## Other responses

- `404`: Agent or provider not found (`provider_not_found`)
- `409`: The agent has no primary provider (`primary_required`)
- `422`: A fallback was refused: `too_many_fallbacks`, `duplicate_fallback`, `fallback_model_not_allowed`, `fallback_missing_model`, `fallback_missing_credential`, `fallback_blocked_by_policy` or `fallback_residency_mismatch`

## Changes

- **2026-10-26** `3e25bef24f8f`: 3 info
  - added the optional property `coding_tool` to the response with the `200` status
  - added the optional property `hosted_tools` to the response with the `200` status
  - added the optional property `sub_agents_summary` to the response with the `200` status
- **2026-10-08** `1882866431ad`: 2 info
  - added the optional property `purpose` to the response with the `200` status
  - added the optional property `purpose_mode` to the response with the `200` status
- **2026-10-04** `b475b750a0b7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/xenovia/apis/controlplane/changes/api/v1/agents/:agent_id/fallbacks/put.md)

---

[API](https://skmtc.dev/xenovia/apis/controlplane.md) - [All operations](https://skmtc.dev/xenovia/apis/controlplane/llms.txt) - [OpenAPI document](https://skmtc.dev/xenovia/apis/controlplane/revisions/3e25bef24f8f?raw)