Router Configuration Get and Update API

# Retrieve current config
curl -X GET "https://router.example.com/v1/router/config" \
  -H "Authorization: Bearer <api-key>"

# Update config (admin only)
curl -X PUT "https://router.example.com/v1/router/config" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"listeners":[{"address":"0.0.0.0","port":8080}],"providers":[],"entrypoints":[],"recipes":[],"global":{}}'

{
  "config": {
    "listeners": [{"address": "0.0.0.0", "port": 8080}],
    "providers": [
      {
        "name": "openai",
        "default_model": "gpt-4o",
        "models": [
          {"name": "gpt-4o", "backend_ref": "openai/gpt-4o"}
        ]
      }
    ],
    "entrypoints": [
      {"model": "default", "router": "main", "recipe": "semantic-router"}
    ],
    "recipes": [
      {"name": "semantic-router", "type": "semantic"}
    ],
    "global": {
      "auth": "config/auth.yaml",
      "keys": "config/keys.yaml",
      "users": "config/users.yaml"
    }
  }
}

# Retrieve current config
curl -X GET "https://router.example.com/v1/router/config" \
  -H "Authorization: Bearer <api-key>"

# Update config (admin only)
curl -X PUT "https://router.example.com/v1/router/config" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"listeners":[{"address":"0.0.0.0","port":8080}],"providers":[],"entrypoints":[],"recipes":[],"global":{}}'

{
  "config": {
    "listeners": [{"address": "0.0.0.0", "port": 8080}],
    "providers": [
      {
        "name": "openai",
        "default_model": "gpt-4o",
        "models": [
          {"name": "gpt-4o", "backend_ref": "openai/gpt-4o"}
        ]
      }
    ],
    "entrypoints": [
      {"model": "default", "router": "main", "recipe": "semantic-router"}
    ],
    "recipes": [
      {"name": "semantic-router", "type": "semantic"}
    ],
    "global": {
      "auth": "config/auth.yaml",
      "keys": "config/keys.yaml",
      "users": "config/users.yaml"
    }
  }
}

Use the Config endpoint to inspect or replace the live router configuration. A GET request returns the current YAML v0.3 config serialized as JSON. A PUT request replaces the entire config with a validated object. Only admin callers may update configuration. The configuration is organized into top-level blocks: listeners, providers, entrypoints, recipes, and global.

Endpoint

GET /v1/router/config

PUT /v1/router/config

Authentication

Authenticate with a session cookie or pass Authorization: Bearer <api-key>. The PUT method requires an admin role.

GET Response

object

The current router configuration.

Show properties

array

Bind addresses and ports the router listens on.

Show items

string

Bind address.

integer

Bind port.

array

Provider definitions with default models and backend references.

Show items

string

Provider identifier.

string

Fallback model when none is specified.

array

Backend references for each model.

Show items

string

Model name.

string

Backend endpoint or identifier.

array

Virtual model mappings to router and recipe combinations.

Show items

string

Virtual model name exposed to clients.

string

Router identifier.

string

Recipe identifier.

array

Routing recipes, classified as semantic or agent.

Show items

string

Recipe identifier.

string

Recipe class. semantic (routing.) or agent (agent.).

object

Global settings such as auth paths, keys paths, and users paths.

Show properties

string

Authentication configuration path.

string

API keys configuration path.

string

Users configuration path.

PUT Request Body

array

Bind addresses and ports.

array

required

Provider definitions.

array

required

Virtual model mappings.

array

required

Routing recipes.

object

required

Global settings.

PUT Response

boolean

Whether the new configuration was accepted and applied.

# Retrieve current config
curl -X GET "https://router.example.com/v1/router/config" \
  -H "Authorization: Bearer <api-key>"

# Update config (admin only)
curl -X PUT "https://router.example.com/v1/router/config" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"listeners":[{"address":"0.0.0.0","port":8080}],"providers":[],"entrypoints":[],"recipes":[],"global":{}}'

{
  "config": {
    "listeners": [{"address": "0.0.0.0", "port": 8080}],
    "providers": [
      {
        "name": "openai",
        "default_model": "gpt-4o",
        "models": [
          {"name": "gpt-4o", "backend_ref": "openai/gpt-4o"}
        ]
      }
    ],
    "entrypoints": [
      {"model": "default", "router": "main", "recipe": "semantic-router"}
    ],
    "recipes": [
      {"name": "semantic-router", "type": "semantic"}
    ],
    "global": {
      "auth": "config/auth.yaml",
      "keys": "config/keys.yaml",
      "users": "config/users.yaml"
    }
  }
}

PIN API

ROUTER API

AGENT API

Router Configuration Get and Update API

Endpoint

Authentication

GET Response

PUT Request Body

PUT Response

​Endpoint

​Authentication

​GET Response

​PUT Request Body

​PUT Response

Endpoint

Authentication

GET Response

PUT Request Body

PUT Response