> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace an agent's fallback providers

> 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.



## OpenAPI

````yaml https://cp.xenovia.io/openapi.json put /api/v1/agents/{agent_id}/fallbacks
openapi: 3.1.0
info:
  title: Xenovia Control Plane API
  version: 1.0.0
  description: >-
    Management API for agents, providers, policies, telemetry, alerts and
    organization settings.
servers:
  - url: https://cp.xenovia.io
    description: Production
security:
  - BearerAuth: []
paths:
  /api/v1/agents/{agent_id}/fallbacks:
    put:
      tags:
        - agents
      summary: Replace an agent's fallback providers
      description: |-
        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.
      operationId: put_agent_fallbacks_route_api_v1_agents__agent_id__fallbacks_put
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Agent Id
        - name: X-Request-ID
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Request-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentFallbacksUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRead'
        '404':
          description: Agent or provider not found (`provider_not_found`)
        '409':
          description: The agent has no primary provider (`primary_required`)
        '422':
          description: >-
            A fallback was refused: `too_many_fallbacks`, `duplicate_fallback`,
            `fallback_missing_model`, `fallback_missing_credential`,
            `fallback_blocked_by_policy` or `fallback_residency_mismatch`
components:
  schemas:
    AgentFallbacksUpdate:
      properties:
        fallbacks:
          items:
            $ref: '#/components/schemas/AgentFallbackEntry'
          type: array
          title: Fallbacks
        routing:
          anyOf:
            - $ref: '#/components/schemas/AgentRoutingUpdate'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - fallbacks
      title: AgentFallbacksUpdate
      description: |-
        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.
    AgentRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        org_id:
          type: string
          format: uuid
          title: Org Id
        owner_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Owner Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        status:
          $ref: '#/components/schemas/AgentStatus'
        source:
          $ref: '#/components/schemas/AgentSource'
        provider_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Provider Id
        provider:
          anyOf:
            - $ref: '#/components/schemas/AgentProviderSummary'
            - type: 'null'
        deployment_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Deployment Id
        fallbacks:
          items:
            $ref: '#/components/schemas/AgentFallbackRead'
          type: array
          title: Fallbacks
        routing:
          $ref: '#/components/schemas/AgentRouting'
        primary_capabilities:
          anyOf:
            - $ref: '#/components/schemas/ModelCapabilities'
            - type: 'null'
        primary_residency:
          type: string
          enum:
            - us
            - eu
            - apac
            - global
            - unknown
          title: Primary Residency
          default: unknown
        agent_url:
          type: string
          title: Agent Url
          description: >-
            Endpoint base URL for this agent. Cloud agents render
            `https://runtime.xenovia.io/{agent_id}/v1`; hybrid agents render
            their deployment's ingress URL plus `/{agent_id}/v1`.
          readOnly: true
      type: object
      required:
        - id
        - created_at
        - updated_at
        - org_id
        - owner_id
        - name
        - description
        - system_prompt
        - status
        - source
        - provider_id
        - provider
        - agent_url
      title: AgentRead
    AgentFallbackEntry:
      properties:
        provider_id:
          type: string
          format: uuid
          title: Provider Id
        model:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Model
      additionalProperties: false
      type: object
      required:
        - provider_id
      title: AgentFallbackEntry
    AgentRoutingUpdate:
      properties:
        fail_over_on:
          anyOf:
            - items:
                type: string
                enum:
                  - unreachable
                  - timeout
                  - rate_limited
                  - server_error
                  - overloaded
                  - setup_fault
              type: array
            - type: 'null'
          title: Fail Over On
        attempt_timeout_s:
          anyOf:
            - type: integer
              maximum: 600
              minimum: 10
            - type: 'null'
          title: Attempt Timeout S
        total_budget_s:
          anyOf:
            - type: integer
              maximum: 900
              minimum: 10
            - type: 'null'
          title: Total Budget S
        first_token_timeout_s:
          anyOf:
            - type: integer
              maximum: 120
              minimum: 1
            - type: 'null'
          title: First Token Timeout S
        breaker_enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Breaker Enabled
        same_residency:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Same Residency
      additionalProperties: false
      type: object
      title: AgentRoutingUpdate
      description: Part or all of AgentRouting; an omitted field keeps its value.
    AgentStatus:
      type: string
      enum:
        - draft
        - active
      title: AgentStatus
    AgentSource:
      type: string
      enum:
        - auto
        - manual
      title: AgentSource
    AgentProviderSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        provider:
          type: string
          title: Provider
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
      type: object
      required:
        - id
        - name
        - provider
        - model
      title: AgentProviderSummary
    AgentFallbackRead:
      properties:
        position:
          type: integer
          title: Position
        provider_id:
          type: string
          format: uuid
          title: Provider Id
        provider:
          $ref: '#/components/schemas/AgentProviderSummary'
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        model_override:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Override
        residency:
          type: string
          enum:
            - us
            - eu
            - apac
            - global
            - unknown
          title: Residency
          default: unknown
        capabilities:
          anyOf:
            - $ref: '#/components/schemas/ModelCapabilities'
            - type: 'null'
      type: object
      required:
        - position
        - provider_id
        - provider
        - model
      title: AgentFallbackRead
    AgentRouting:
      properties:
        fail_over_on:
          items:
            type: string
            enum:
              - unreachable
              - timeout
              - rate_limited
              - server_error
              - overloaded
              - setup_fault
          type: array
          title: Fail Over On
        attempt_timeout_s:
          type: integer
          maximum: 600
          minimum: 10
          title: Attempt Timeout S
          default: 120
        total_budget_s:
          type: integer
          maximum: 900
          minimum: 10
          title: Total Budget S
          default: 300
        first_token_timeout_s:
          anyOf:
            - type: integer
              maximum: 120
              minimum: 1
            - type: 'null'
          title: First Token Timeout S
        breaker_enabled:
          type: boolean
          title: Breaker Enabled
          default: true
        same_residency:
          type: boolean
          title: Same Residency
          default: false
      additionalProperties: false
      type: object
      title: AgentRouting
      description: An agent's failover settings, always whole (every default filled).
    ModelCapabilities:
      properties:
        context_window:
          anyOf:
            - type: integer
            - type: 'null'
          title: Context Window
        max_output:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Output
        vision:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Vision
        tools:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Tools
        reasoning:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Reasoning
      type: object
      title: ModelCapabilities
      description: |-
        What a model can take, from the public model directory (models.dev);
        each member is null when the directory does not say (assume capable).
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token: an organization API key (`ak_…`) created under Settings →
        API Keys, or a dashboard user session token. Agent keys (`xe_…`) are not
        accepted here. Endpoints marked as user-only in their description reject
        organization keys with `403`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.