Skip to content

List Routers

GET/v1/routers

Overview

Requires an active workspace membership with owner, admin, developer, or viewer role. Billing-only members and inference API keys are rejected. workspace_id is always required; a router ID from a different authorized workspace returns 404. Results include mutable drafts and current optimistic generations, ordered by router ID ascending. Pass next_cursor as cursor with the same filters to continue. Archived routers are omitted by default.

Authorization

Authorizationstring · headerRequired

Workspace session token sent as Bearer <token>. Authentication guide

Parameters

workspace_idquery · stringRequired

Explicit workspace scope; the authenticated session must hold a permitted active membership.

statusquery · string

searchquery · string

Case-insensitive literal substring of name or slug.

cursorquery · string

Exclusive router ID cursor returned in next_cursor.

limitquery · integer

Responses

200Operation completed.

application/json

dataobject[]Required

Show nested fields

idstringRequired

workspace_idstringRequired

slugstringRequired

aliasstringRequired

Example: "router/coding"

namestringRequired

taskstringRequired

generationintegerRequired

Optimistic version of the router record. Every successful mutation increments it. Send the observed value as expected_generation; stale values return 409.

Minimum 1 · Maximum 2147483647

draftobjectRequired

Versioned declarative LLM router configuration, normalized to at most 65536 UTF-8 JSON bytes. Unknown fields and undocumented null values are rejected. Structurally valid but incomplete drafts are permitted; validation/publication enforce final-default, nonempty pools, uniqueness, exact weights and current model eligibility.

Example: {"schema_version":1,"task":"llm","protocol":"chat","requirements":[],"defaults":{},"request_overrides":[],"policy":{"max_input_tokens":128000,"max_output_tokens":8192,"deadline_ms":120000,"regions":[],"zero_retention":false},"routes":[{"id":"default","name":"Default","condition":null,"defaults":{},"variants":[{"id":"primary","name":"Primary","weight":100,"selection":{"mode":"ordered","models":[]},"defaults":{}}]}]}

Show nested fields

schema_versionintegerRequired

taskstringRequired

protocolstringRequired

Values: "chat""responses""messages"

requirementsstring[]

Default: []

Show nested fields

See the OpenAPI schema for this nested object.

defaultsobject

Field-wise inheritance: router defaults, then route defaults, then variant defaults, then explicitly permitted request parameters. Omitted fields inherit; null does not clear a field. max_tokens defaults to policy.max_output_tokens and cannot exceed that policy. Every effective and overridable parameter must be supported by every selected model.

Show nested fields

See the OpenAPI schema for this nested object.

request_overridesstring[]

Default: []

Show nested fields

See the OpenAPI schema for this nested object.

policyobject

Declarative upper limits, intersected with current operator/workspace/model restrictions. A model must support the full configured input plus output context budget. Region and zero-retention requirements cannot widen workspace policy.

Show nested fields

See the OpenAPI schema for this nested object.

routesobject[]Required

Show nested fields

See the OpenAPI schema for this nested object.

active_revisioninteger | nullRequired

Show nested fields

Option 1: integer

See the OpenAPI schema for this nested object.

Option 2: null

See the OpenAPI schema for this nested object.

archived_atstring | nullRequired

Show nested fields

Option 1: string

See the OpenAPI schema for this nested object.

Option 2: null

See the OpenAPI schema for this nested object.

created_atstringRequired

updated_atstringRequired

next_cursorstring | nullRequired

Show nested fields

Option 1: string

string

Option 2: null

null

400Request validation failed.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

401Authentication is missing or invalid.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

403Authenticated principal lacks permission.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

404Resource was not found.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

429Rate limit exceeded.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

500Internal server error.

application/json

errorobjectRequired

Show nested fields

codestringRequired

messagestringRequired

paramstring | null

request_idstring | null

metadataobject

Typed detail for some refusals. budget_exceeded (402): limit (key_budget or workspace_budget) and budget with scope, period, limit, usage and resets_at. key_limit_exceeded (402): limit key_spend_limit. access_denied (403): policy (workspace or key), rule (models, providers or products), product, provider and model.

Replace uppercase placeholders before running. JavaScript examples require Node.js 22 or later; Python examples require requests. WebSocket examples require the Node.js ws package. See setup for credentials.

curl --fail --show-error --request GET \
  --url "$AUDIOLAB_API_URL/v1/routers?workspace_id=VALUE" \
  --header "Authorization: Bearer $AUDIOLAB_SESSION"

{
  "data": [
    {
      "id": "VALUE",
      "workspace_id": "VALUE",
      "slug": "VALUE",
      "alias": "router/coding",
      "name": "VALUE",
      "task": "VALUE",
      "generation": 1,
      "draft": {
        "schema_version": 1,
        "task": "llm",
        "protocol": "chat",
        "requirements": [],
        "defaults": {},
        "request_overrides": [],
        "policy": {
          "max_input_tokens": 128000,
          "max_output_tokens": 8192,
          "deadline_ms": 120000,
          "regions": [],
          "zero_retention": false
        },
        "routes": [
          {
            "id": "default",
            "name": "Default",
            "condition": null,
            "defaults": {},
            "variants": [
              {
                "id": "primary",
                "name": "Primary",
                "weight": 100,
                "selection": {
                  "mode": "ordered",
                  "models": []
                },
                "defaults": {}
              }
            ]
          }
        ]
      },
      "active_revision": {},
      "archived_at": {}
    }
  ],
  "next_cursor": "VALUE"
}

Example responses · See schemas for all fields