listAllRoutes.md

List all model routes

Returns every model route in the org, with their owning provider's name.

OpenAPI

openapi: 3.1.0
info:
  title: Barndoor LLM Gateway API
  version: 1.0.0
  description: >
    REST API for the Barndoor LLM Gateway: configure providers, model routes,
    pricing, governance, and operate a multi-provider LLM platform
    programmatically.

All endpoints in this document are scoped to your organization. They are the
    same APIs powering the Barndoor portal under **LLM Configuration**,
    **LLM Controls**, and **Settings - My Models**, exposed for teams that
    prefer scripting over the UI.

## Base URL

All requests are issued against your Barndoor instance:

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

Replace `app.barndoor.ai` with your tenant host if you run on Enterprise.

## Authentication

Endpoints accept a JWT Bearer token issued by your Barndoor identity
provider. Tokens can be obtained interactively via the Barndoor SDK:

```ts
const sdk = await loginInteractive();
```

The token must be sent in the `Authorization` header on every request:

```
Authorization: Bearer eyJhbGciOi...
```

Note: the `bd-...` API keys you create through these endpoints are for
runtime LLM traffic (`/v1/chat/completions`, `/v1/messages`, etc.), not for
administrative calls. Administrative endpoints require a user/admin JWT.

## Permissions

Most endpoints require an `admin` (or higher) role on the calling user.
Read-only endpoints are typically accessible by all authenticated users.
Read-only listings under `/user/...` are scoped to the authenticated user.

## Errors

Errors are returned as JSON with a stable shape:

```json
{ "error": "BadRequest", "message": "request_timeout_secs must be between 1
and 3600" }
```

### Paths

#### /admin/model-mappings:

- **get**:
  - **tags**: Model Routes
  - **summary**: List all model routes
  - **description**: Returns every model route in the org, with their owning provider's name.
  - **operationId**: listAllModelRoutes
  - **responses**:
    - '200':
      - **description**: List of routes
      - **content**:
        - application/json:
          - **schema**:
            - type: array
              - **items**:
                - $ref: '#/components/schemas/ModelRoute'

### Components

#### Schemas

- **ModelRoute**:
  - **type**: object
  - **description**: |
    A Model Route maps a client-facing alias to a specific provider and
    upstream model. One alias may have multiple routes; the gateway tries
    them in `priority` order and fails over on upstream errors.
  - **required**:
    - id
    - provider_id
    - model_alias
    - upstream_model
    - enabled
    - priority
    - retry_on_429_count
    - retry_on_429_max_wait_secs
    - bare_alias
  - **properties**:
    - id:
        - type: string
        - format: uuid
    - provider_id:
        - type: string
        - format: uuid
    - provider_name:
        - type: string
        - description: Present on cross-provider listings
    - model_alias:
        - type: string
        - example: gpt-4o-mini
    - upstream_model:
        - type: string
        - example: gpt-4o-mini-2024-07-18
    - enabled:
        - type: boolean
    - priority:
        - type: integer
        - description: Lower numbers are tried first within the same alias
    - retry_on_429_count:
        - type: integer
        - minimum: 0
        - maximum: 10
        - description: Same-route retries on upstream 429 before failing over
    - retry_on_429_max_wait_secs:
        - type: integer
        - minimum: 0
        - maximum: 180
        - description: >-
          Cap on honoring upstream `Retry-After` (0 = use small built-in
          default)
    - bare_alias:
        - type: boolean
        - description: |
          When `true` the route participates in plain-alias resolution
          (e.g. `model: "gpt-4o-mini"`). When `false` it is only
          addressable as `<provider>/<upstream-model>`.
    - stream_idle_timeout_secs:
        - type: integer
        - nullable: true
        - minimum: 1
        - maximum: 1800
    - max_concurrent_requests:
        - type: integer
        - nullable: true
        - minimum: 1
        - maximum: 10000
        - description: Cap on in-flight requests per gateway pod against this route
    - request_timeout_secs:
        - type: integer
        - nullable: true
        - minimum: 1
        - maximum: 3600
    - budget_status:
        - allOf:
            - $ref: '#/components/schemas/BudgetTargetStatus'
          - description: |
            Present (and only present) when one of this route's targeted budgets
            with `action_on_exhaust = block` is currently exhausted. The
            runtime drops this route until the budget rolls over.

- **BudgetTargetStatus**:
  - **type**: object
  - **description**: |
    Snapshot of the first budget that would block this route (if any).
    Surfaced on listings so admin UIs can show a "disabled by budget" pill.
  - **properties**:
    - scope:
        - type: string
        - example: org
    - target_kind:
        - type: string
        - enum:
          - llm_provider
          - model
          - model_alias
    - target_id:
        - type: string
    - budget_id:
        - type: string
        - format: uuid
    - budget_name:
        - type: string
    - period:
        - type: string
        - example: monthly
    - usage:
        - type: number
    - limit:
        - type: number

### Security Schemes

- **BearerAuth**:
  - **type**: http
  - **scheme**: bearer
  - **bearerFormat**: JWT
  - **description**: |
    JWT obtained through Barndoor's authentication flow. Pass the token
    verbatim in `Authorization: Bearer <token>`. Use the Barndoor SDK's
    `loginInteractive()` helper to obtain a token in scripts and notebooks.