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

# Update a model route

> Updates a model route. Only the fields you send are changed. When your organization requires pricing for model routes, an enabled route must still match a pricing rule after the update; setting `enabled: false` is always allowed.



## OpenAPI

````yaml api-reference/llm-gateway-openapi.yml put /admin/model-mappings/{id}
openapi: 3.1.0
info:
  title: Barndoor LLM Gateway Admin API
  version: 1.0.0
  description: >
    Configure the Barndoor LLM Gateway programmatically: credentials and
    providers,

    model routes and route groups, pricing, routing policies and rules, launch
    profiles,

    budgets, rate limits, model access, API keys, and organization-wide
    governance settings.


    These are the same APIs the Barndoor app uses under **LLM Management**, and
    the

    Barndoor Terraform provider manages its LLM Gateway resources through them.
    Every

    endpoint is scoped to the organization of the calling token.


    ## Base URL


    ```

    https://app.barndoor.ai/api/llm-gateway

    ```


    For a dedicated deployment, replace `app.barndoor.ai` with the host you sign
    in to.


    ## Authentication


    Send an access token from Barndoor's identity provider in the
    `Authorization` header:


    ```

    Authorization: Bearer <access-token>

    ```


    For scripts and CI, use a service-account token from the OAuth 2.0
    client-credentials

    grant, as the Terraform provider does. The caller needs the admin role in
    the

    organization.


    The `bd-...` API keys you create with these endpoints are for LLM traffic

    (`/v1/chat/completions`, `/v1/messages`, and so on), not for these
    administrative calls.


    ## Partial updates


    Most `PUT` endpoints change only the fields you send. Where a field can be
    cleared,

    send it as `null`; omitting it leaves it unchanged. The exceptions are
    called out on

    the endpoint: `PUT /admin/governance-config` replaces the whole
    configuration,

    `PUT /admin/routing-rules/{id}` replaces the whole rule, and

    `PUT /admin/agent-runtime-profiles/{slug}` replaces the profile's models.


    ## Errors


    Errors are returned as JSON:


    ```json

    { "error": { "message": "retry_on_429_count must be between 0 and 10",
    "type": "invalid_request_error" } }

    ```
  contact:
    name: Barndoor Support
    url: https://barndoor.ai
servers:
  - url: https://{host}/api/llm-gateway
    description: Your Barndoor platform host.
    variables:
      host:
        default: app.barndoor.ai
        description: >-
          The host serving your Barndoor deployment. Use the default for
          Barndoor SaaS; for a dedicated deployment, use the host you sign in
          to.
security:
  - BearerAuth: []
tags:
  - name: Credentials
    description: >-
      Stored upstream secrets (API keys, AWS roles, Google credentials) that
      providers reference
  - name: Providers
    description: Named upstream providers backed by a credential and a model family
  - name: Model Routes
    description: >-
      Map caller-facing aliases to upstream models on one or more providers,
      with failover order, retries, timeouts, and cooldowns
  - name: Route Groups
    description: >-
      Named sets of model aliases that model access policies can target as one
      unit
  - name: Model Pricing
    description: >-
      Versioned per-million-token costs used for cost reporting and cost-based
      budgets
  - name: Routing Policies
    description: Model aliases that pick one of several model slots for each request
  - name: Routing Rules
    description: >-
      Plain-English rules that set a minimum slot or forbid slots on a routing
      policy
  - name: Launch Profiles
    description: >-
      Models and capabilities applied when members start an agent with barndoor
      run
  - name: Rate Limits
    description: Requests-per-minute and tokens-per-minute ceilings
  - name: Budgets
    description: Daily, weekly, or monthly token and cost ceilings
  - name: Model Access
    description: >-
      Allowlist and denylist policies for models, providers, aliases, and route
      groups
  - name: Governance
    description: Organization-wide LLM Gateway settings
  - name: API Keys
    description: Organization-managed `bd-...` gateway API keys for LLM traffic
paths:
  /admin/model-mappings/{id}:
    put:
      tags:
        - Model Routes
      summary: Update a model route
      description: >-
        Updates a model route. Only the fields you send are changed. When your
        organization requires pricing for model routes, an enabled route must
        still match a pricing rule after the update; setting `enabled: false` is
        always allowed.
      operationId: updateRoute
      parameters:
        - name: id
          in: path
          description: Record ID (UUID)
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateModelMappingRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelMapping'
        '400':
          description: Invalid request. The error message says which field or rule failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Your role does not allow this action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such record in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflicts with an existing record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporarily unavailable; safe to retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
components:
  schemas:
    UpdateModelMappingRequest:
      type: object
      properties:
        bare_alias:
          type:
            - boolean
            - 'null'
        change_note:
          type:
            - string
            - 'null'
          description: >-
            Optional note explaining this change. Omitting it clears the
            previous note.
        cooldown_429_default_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: Same as on create. Omit to keep the stored value.
        cooldown_base_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: Same as on create. Omit to keep the stored value.
        cooldown_failure_threshold:
          type:
            - integer
            - 'null'
          format: int32
          description: Same as on create. Omit to keep the stored value.
        cooldown_max_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: Same as on create. Omit to keep the stored value.
        cooldown_overloaded_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: Same as on create. Omit to keep the stored value.
        cooldown_window_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: Same as on create. Omit to keep the stored value.
        enabled:
          type:
            - boolean
            - 'null'
        model_alias:
          type:
            - string
            - 'null'
        priority:
          type:
            - integer
            - 'null'
          format: int32
        request_timeout_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Total-request timeout for non-streaming requests, in seconds
            (1–600). Omit to leave unchanged; send `null` to clear.
        retry_on_429_count:
          type:
            - integer
            - 'null'
          format: int32
        retry_on_429_max_wait_secs:
          type:
            - integer
            - 'null'
          format: int32
        stream_idle_timeout_secs:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Streaming idle timeout, in seconds (1–300). Omit to leave unchanged;
            send `null` to clear.
        upstream_model:
          type:
            - string
            - 'null'
    ModelMapping:
      allOf:
        - $ref: '#/components/schemas/CooldownPolicy'
        - $ref: '#/components/schemas/ChangeAttribution'
        - type: object
          required:
            - id
            - provider_id
            - model_alias
            - upstream_model
            - enabled
            - priority
            - retry_on_429_count
            - retry_on_429_max_wait_secs
            - bare_alias
            - source
          properties:
            auto_disabled_reason:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/AutoDisabledReason'
                  description: >-
                    Set when the gateway disabled this route because the model
                    left the provider's catalog. Any admin change to `enabled`
                    clears it.
            bare_alias:
              type: boolean
              description: >-
                Whether the route answers requests that name the alias alone.
                When `false`, the model is reachable only as
                `<provider>/<upstream_model>`. Custom aliases are always `true`.
            enabled:
              type: boolean
            id:
              type: string
              format: uuid
            model_alias:
              type: string
            priority:
              type: integer
              format: int32
              description: >-
                Failover order among routes serving the same alias; lower is
                tried first.
            provider_id:
              type: string
              format: uuid
            request_timeout_secs:
              type:
                - integer
                - 'null'
              format: int32
              description: >-
                Total-request timeout for non-streaming requests, in seconds
                (1–600).
            retry_on_429_count:
              type: integer
              format: int32
              description: Same-route retries on upstream 429. 0 means immediate failover.
            retry_on_429_max_wait_secs:
              type: integer
              format: int32
              description: >-
                Longest upstream `Retry-After` to honor, in seconds. `0` uses a
                short built-in wait and ignores the header.
            source:
              $ref: '#/components/schemas/ModelSource'
              description: >-
                Whether the model was chosen from the catalog or typed in when
                the route was created.
            stream_idle_timeout_secs:
              type:
                - integer
                - 'null'
              format: int32
              description: >-
                Idle timeout between chunks of a streaming response, in seconds
                (1–300).
            upstream_model:
              type: string
      description: A model route.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              description: Human-readable explanation of what went wrong.
            type:
              type: string
              description: >-
                Error category, such as `invalid_request_error`,
                `authentication_error`, `permission_error`, `not_found_error`,
                or `conflict_error`.
            code:
              type:
                - string
                - 'null'
              description: Machine-readable code, when one applies.
      example:
        error:
          message: retry_on_429_count must be between 0 and 10
          type: invalid_request_error
    CooldownPolicy:
      type: object
      description: >-
        The route's cooldown settings. Routes that target the same provider and
        upstream model share one health state; each request applies the settings
        of the route it resolved to.
      required:
        - cooldown_failure_threshold
        - cooldown_window_secs
        - cooldown_base_secs
        - cooldown_max_secs
        - cooldown_429_default_secs
        - cooldown_overloaded_secs
      properties:
        cooldown_429_default_secs:
          type: integer
          format: int32
          description: >-
            Cooldown after an upstream 429 with no usable `Retry-After`, in
            seconds.
        cooldown_base_secs:
          type: integer
          format: int32
          description: >-
            First cooldown window, in seconds. Doubles after each failed
            recovery probe, up to `cooldown_max_secs`.
        cooldown_failure_threshold:
          type: integer
          format: int32
          description: >-
            Gateway failures within `cooldown_window_secs` that put the route in
            cooldown. `0` disables cooldowns for the route.
        cooldown_max_secs:
          type: integer
          format: int32
          description: Longest cooldown window, in seconds.
        cooldown_overloaded_secs:
          type: integer
          format: int32
          description: >-
            Cooldown after an upstream 529 (overloaded) with no usable
            `Retry-After`, in seconds. `0` treats a 529 as an ordinary failure.
        cooldown_window_secs:
          type: integer
          format: int32
          description: Length of the rolling failure window, in seconds.
    ChangeAttribution:
      type: object
      description: >-
        Who created and last changed the record, and why. Records created before
        attribution was added have no values until their next change.
      properties:
        created_by_email:
          type:
            - string
            - 'null'
        created_by_name:
          type:
            - string
            - 'null'
        created_by_user_id:
          type:
            - string
            - 'null'
          format: uuid
        last_change_note:
          type:
            - string
            - 'null'
          description: Note explaining the last change.
        last_modified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the last attributed change was made.
        last_modified_by_email:
          type:
            - string
            - 'null'
        last_modified_by_name:
          type:
            - string
            - 'null'
        last_modified_by_user_id:
          type:
            - string
            - 'null'
          format: uuid
    AutoDisabledReason:
      type: string
      description: >-
        Set when the gateway, not an admin, disabled a route. `catalog_retired`:
        the provider's model sync mode is `full` and Barndoor's catalog no
        longer lists the model.
      enum:
        - catalog_retired
    ModelSource:
      type: string
      description: >-
        `catalog` (picked from the provider catalog) or `custom` (typed in). Set
        when the route is created and never changed.
      enum:
        - catalog
        - custom
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An access token from Barndoor's identity provider, sent as
        `Authorization: Bearer <token>`. Use a service-account token from the
        OAuth 2.0 client-credentials grant for scripts and CI, or a signed-in
        user's token. The caller needs the admin role in the organization.
        Gateway API keys (`bd-...`) are not accepted here.

````

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