Skip to Content
Launching the open-source gateway

Create a route

POSThttps://api.respan.ai/api/routes/

Send the route’s name as model to use it. A split route needs an entry with a positive weight; a fallback route ignores weights. The gateway picks up the route within a few seconds.

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

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
Example: {"name":"chat-ab-test","mode":"split","entries":[{"name":"gpt-5.5","weight":3},{"name":"claude-sonnet-4-5-20250929","weight":1}]}
name string Required in parent
The name you send as model. It may contain slashes, and can’t end in :cheapest or :fastest.
Maximum length: 255
mode string Required in parent
fallback tries the entries in order. split picks one by weight, then tries the others.
Allowed: "fallback", "split"
entries array<object> Required in parent
The route’s entries, in order.
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.
Maximum length: 255
entries[].weight number Optional
Share of traffic in a split route. A fallback route ignores it.
Default: 1
Minimum: 0

OpenAPI request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255,
      "description": "The name you send as `model`. It may contain slashes, and can't end in `:cheapest` or `:fastest`."
    },
    "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": "chat-ab-test",
    "mode": "split",
    "entries": [
      {
        "name": "gpt-5.5",
        "weight": 3
      },
      {
        "name": "claude-sonnet-4-5-20250929",
        "weight": 1
      }
    ]
  }
}

Responses

201

The created route.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/Route
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.
Maximum length: 255
mode string Required in parent
fallback tries the entries in order. split picks one by weight, then tries the others.
Allowed: "fallback", "split"
entries array<object> Required in parent
The route’s entries, in order.
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.
Maximum length: 255
entries[].weight number Optional
Share of traffic in a split route. A fallback route ignores it.
Default: 1
Minimum: 0

OpenAPI response schema

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

400

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

application/json

Field Type Requirement Description and constraints
$ object Body
—

OpenAPI response schema

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

409

A route of that name already exists. Change it with PATCH.

application/json

Field Type Requirement Description and constraints
$ object Body
—

OpenAPI response schema

{
  "type": "object"
}
Example
JSON
{
  "detail": "A route of this name already exists."
}

OpenAPI source

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

OpenAPI operation

{
  "summary": "Create a route",
  "operationId": "createRoute",
  "tags": [
    "Routes"
  ],
  "description": "Send the route's name as `model` to use it. A `split` route needs an entry with a positive weight; a `fallback` route ignores weights. The gateway picks up the route within a few seconds.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "maxLength": 255,
              "description": "The name you send as `model`. It may contain slashes, and can't end in `:cheapest` or `:fastest`."
            },
            "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": "chat-ab-test",
            "mode": "split",
            "entries": [
              {
                "name": "gpt-5.5",
                "weight": 3
              },
              {
                "name": "claude-sonnet-4-5-20250929",
                "weight": 1
              }
            ]
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "The created 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."
            ]
          }
        }
      }
    },
    "409": {
      "description": "A route of that name already exists. Change it with PATCH.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          },
          "example": {
            "detail": "A route of this name already exists."
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "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"
      }
    }
  }
}