---
title: "Update a route"
description: "Send `mode`, `entries` or both. A field you leave out keeps its value, and `entries` replaces the whole list."
---

**PATCH** `https://api.respan.ai/api/routes/{name}/`

Send `mode`, `entries` or both. A field you leave out keeps its value, and `entries` replaces the whole list.

## Servers

`https://api.respan.ai` — Respan API Server

## Authentication

### RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: `bearer`; format: `Respan API key`.


```http
Authorization: Bearer $RESPAN_API_KEY
```


**Or:**

### DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: `bearer`; format: `Dashboard JWT`.


```http
Authorization: Bearer $RESPAN_DASHBOARD_JWT
```


## Path parameters


| Parameter | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | `string` | Required | The route's name. It may contain slashes, as in `openai/gpt-6-luna`. |


## Request body

A request body is required.

### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Required body | Example: `{"entries":[{"name":"gpt-5.5","weight":1},{"name":"claude-sonnet-4-5-20250929","weight":1}]}` |
| `mode` | `string` | Optional | `fallback` tries the entries in order. `split` picks one by weight, then tries the others.<br />Allowed: `"fallback"`, `"split"` |
| `entries` | `array<object>` | Optional | The route's entries, in order.<br />Minimum items: `1` |
| `entries[]` | `object` | Array item | Reference: `#/components/schemas/RouteEntry` |
| `entries[].name` | `string` | Required in parent | A model, a foundation model, a `<provider>/<model>` name, or a Respan route.<br />Maximum length: `255` |
| `entries[].weight` | `number` | Optional | Share of traffic in a `split` route. A `fallback` route ignores it.<br />Default: `1`<br />Minimum: `0` |


<details class="api-schema-source">
<summary>OpenAPI request schema</summary>


```json
{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "fallback",
        "split"
      ],
      "description": "`fallback` tries the entries in order. `split` picks one by weight, then tries the others."
    },
    "entries": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/components/schemas/RouteEntry"
      },
      "description": "The route's entries, in order."
    }
  },
  "example": {
    "entries": [
      {
        "name": "gpt-5.5",
        "weight": 1
      },
      {
        "name": "claude-sonnet-4-5-20250929",
        "weight": 1
      }
    ]
  }
}
```

</details>

## Responses

### 200

The updated route.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | Reference: `#/components/schemas/Route`<br />Example: `{"name":"support-bot","mode":"fallback","entries":[{"name":"gpt-5.5","weight":1},{"name":"claude-sonnet-4-5-20250929","weight":1}]}` |
| `name` | `string` | Required in parent | The name you send as `model`. It may contain slashes.<br />Maximum length: `255` |
| `mode` | `string` | Required in parent | `fallback` tries the entries in order. `split` picks one by weight, then tries the others.<br />Allowed: `"fallback"`, `"split"` |
| `entries` | `array<object>` | Required in parent | The route's entries, in order.<br />Minimum items: `1` |
| `entries[]` | `object` | Array item | Reference: `#/components/schemas/RouteEntry` |
| `entries[].name` | `string` | Required in parent | A model, a foundation model, a `<provider>/<model>` name, or a Respan route.<br />Maximum length: `255` |
| `entries[].weight` | `number` | Optional | Share of traffic in a `split` route. A `fallback` route ignores it.<br />Default: `1`<br />Minimum: `0` |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "$ref": "#/components/schemas/Route"
}
```

</details>

### 400

The route is invalid, for example an entry your project can't call.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object"
}
```

</details>

##### Example


```json
{
  "entries": [
    "Entries must name a model, foundation model or Respan route this project can call. Not found: gpt-unknown."
  ]
}
```


### 404

No route of that name.

#### application/json


| Field | Type | Requirement | Description and constraints |
| --- | --- | --- | --- |
| `$` | `object` | Body | — |


<details class="api-schema-source">
<summary>OpenAPI response schema</summary>


```json
{
  "type": "object"
}
```

</details>

##### Example


```json
{
  "detail": "Route not found."
}
```


## OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

<!-- openapi-operation:start -->
<details class="api-schema-source">
<summary>OpenAPI operation</summary>


```json
{
  "summary": "Update a route",
  "operationId": "updateRoute",
  "tags": [
    "Routes"
  ],
  "parameters": [
    {
      "name": "name",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "The route's name. It may contain slashes, as in `openai/gpt-6-luna`."
    }
  ],
  "description": "Send `mode`, `entries` or both. A field you leave out keeps its value, and `entries` replaces the whole list.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "fallback",
                "split"
              ],
              "description": "`fallback` tries the entries in order. `split` picks one by weight, then tries the others."
            },
            "entries": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/RouteEntry"
              },
              "description": "The route's entries, in order."
            }
          },
          "example": {
            "entries": [
              {
                "name": "gpt-5.5",
                "weight": 1
              },
              {
                "name": "claude-sonnet-4-5-20250929",
                "weight": 1
              }
            ]
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "The updated route.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Route"
          }
        }
      }
    },
    "400": {
      "description": "The route is invalid, for example an entry your project can't call.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          },
          "example": {
            "entries": [
              "Entries must name a model, foundation model or Respan route this project can call. Not found: gpt-unknown."
            ]
          }
        }
      }
    },
    "404": {
      "description": "No route of that name.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          },
          "example": {
            "detail": "Route not found."
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}
```

</details>
<!-- openapi-operation:end -->

<!-- openapi-path-item:start -->
<details class="api-schema-source">
<summary>OpenAPI path metadata</summary>


```json
{}
```

</details>
<!-- openapi-path-item:end -->

<!-- openapi-components:start -->
<details class="api-schema-source">
<summary>Referenced OpenAPI components</summary>


```json
{
  "schemas": {
    "Route": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 255,
          "description": "The name you send as `model`. It may contain slashes."
        },
        "mode": {
          "type": "string",
          "enum": [
            "fallback",
            "split"
          ],
          "description": "`fallback` tries the entries in order. `split` picks one by weight, then tries the others."
        },
        "entries": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/components/schemas/RouteEntry"
          },
          "description": "The route's entries, in order."
        }
      },
      "required": [
        "name",
        "mode",
        "entries"
      ],
      "example": {
        "name": "support-bot",
        "mode": "fallback",
        "entries": [
          {
            "name": "gpt-5.5",
            "weight": 1
          },
          {
            "name": "claude-sonnet-4-5-20250929",
            "weight": 1
          }
        ]
      }
    },
    "RouteEntry": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 255,
          "description": "A model, a foundation model, a `<provider>/<model>` name, or a Respan route."
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "default": 1,
          "description": "Share of traffic in a `split` route. A `fallback` route ignores it."
        }
      },
      "required": [
        "name"
      ]
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}
```

</details>
<!-- openapi-components:end -->