Skip to Content
Launching the open-source gateway

List routes

GEThttps://api.respan.ai/api/routes/

Your project’s routes.

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

Responses

200

The project’s routes.

application/json

Field Type Requirement Description and constraints
$ array<object> Body
—
$[] object Array item
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

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Route"
  }
}

OpenAPI source

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

OpenAPI operation

{
  "summary": "List routes",
  "operationId": "listRoutes",
  "tags": [
    "Routes"
  ],
  "description": "Your project's routes.",
  "responses": {
    "200": {
      "description": "The project's routes.",
      "content": {
        "application/json": {
          "schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Route"
            }
          }
        }
      }
    }
  },
  "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"
      }
    }
  }
}