> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Router Configuration Get and Update API

> Retrieve the current router YAML configuration as JSON, or update it with a validated config object. Admin access required for writes.

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

```http theme={null}
GET /v1/router/config
```

```http theme={null}
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

<ResponseField name="config" type="object">
  The current router configuration.

  <Expandable title="properties">
    <ResponseField name="listeners" type="array">
      Bind addresses and ports the router listens on.

      <Expandable title="items">
        <ResponseField name="address" type="string">
          Bind address.
        </ResponseField>

        <ResponseField name="port" type="integer">
          Bind port.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="providers" type="array">
      Provider definitions with default models and backend references.

      <Expandable title="items">
        <ResponseField name="name" type="string">
          Provider identifier.
        </ResponseField>

        <ResponseField name="default_model" type="string">
          Fallback model when none is specified.
        </ResponseField>

        <ResponseField name="models" type="array">
          Backend references for each model.

          <Expandable title="items">
            <ResponseField name="name" type="string">
              Model name.
            </ResponseField>

            <ResponseField name="backend_ref" type="string">
              Backend endpoint or identifier.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="entrypoints" type="array">
      Virtual model mappings to router and recipe combinations.

      <Expandable title="items">
        <ResponseField name="model" type="string">
          Virtual model name exposed to clients.
        </ResponseField>

        <ResponseField name="router" type="string">
          Router identifier.
        </ResponseField>

        <ResponseField name="recipe" type="string">
          Recipe identifier.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recipes" type="array">
      Routing recipes, classified as semantic or agent.

      <Expandable title="items">
        <ResponseField name="name" type="string">
          Recipe identifier.
        </ResponseField>

        <ResponseField name="type" type="string">
          Recipe class. `semantic` (routing.*) or `agent` (agent.*).
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="global" type="object">
      Global settings such as auth paths, keys paths, and users paths.

      <Expandable title="properties">
        <ResponseField name="auth" type="string">
          Authentication configuration path.
        </ResponseField>

        <ResponseField name="keys" type="string">
          API keys configuration path.
        </ResponseField>

        <ResponseField name="users" type="string">
          Users configuration path.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## PUT Request Body

<ParamField body="listeners" type="array">
  Bind addresses and ports.
</ParamField>

<ParamField body="providers" type="array" required>
  Provider definitions.
</ParamField>

<ParamField body="entrypoints" type="array" required>
  Virtual model mappings.
</ParamField>

<ParamField body="recipes" type="array" required>
  Routing recipes.
</ParamField>

<ParamField body="global" type="object" required>
  Global settings.
</ParamField>

## PUT Response

<ResponseField name="applied" type="boolean">
  Whether the new configuration was accepted and applied.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # 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":{}}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
      }
    }
  }
  ```
</ResponseExample>


## Related topics

- [Router Providers List and Upsert API](/api-reference/router/management/providers.md)
- [Update an Agent](/api-reference/pin/agents/update.md)
- [Router Config Validation API](/api-reference/router/management/validate.md)
- [Get Subagent](/api-reference/agent/subagents/get.md)
- [Reroute Captured Router Request API](/api-reference/router/replay/reroute.md)