Skip to main content
GET
/
router
/
v1
/
routers
/
{router_id}
cURL
curl --location 'https://api.inworld.ai/router/v1/routers/<router_id>' \
--header 'Authorization: Basic <your-api-key>'
{
  "name": "<string>",
  "displayName": "<string>",
  "routes": [
    {
      "route": {
        "route_id": "<string>",
        "variants": [
          {
            "variant": {
              "variant_id": "<string>",
              "model_id": "<string>",
              "model_selection": {
                "models": [
                  "<string>"
                ],
                "sort": [
                  {
                    "metric": "SORT_METRIC_UNSPECIFIED",
                    "direction": "SORT_DIRECTION_UNSPECIFIED"
                  }
                ],
                "ignore": [
                  "<string>"
                ],
                "provider": {
                  "order": [
                    "<string>"
                  ],
                  "allow_fallbacks": true
                }
              },
              "text_generation_config": {
                "max_tokens": 123,
                "top_p": 123,
                "temperature": 123,
                "repetition_penalty": 123,
                "frequency_penalty": 123,
                "presence_penalty": 123,
                "stop_sequences": [
                  "<string>"
                ],
                "seed": 123,
                "logit_bias": [
                  {
                    "token_id": "<string>",
                    "bias_value": 123
                  }
                ],
                "reasoning": {
                  "effort": "unspecified",
                  "max_tokens": 123,
                  "exclude": true
                }
              },
              "message_templates": [
                {
                  "role": "<string>",
                  "content": "<string>",
                  "content_items": [
                    {
                      "text": "<string>"
                    }
                  ],
                  "tool_calls": [
                    {
                      "id": "<string>",
                      "name": "<string>",
                      "args": "<string>"
                    }
                  ],
                  "tool_call_id": "<string>"
                }
              ]
            },
            "weight": 123
          }
        ]
      },
      "condition": {
        "cel_expression": "<string>"
      }
    }
  ],
  "defaultRoute": {
    "route_id": "<string>",
    "variants": [
      {
        "variant": {
          "variant_id": "<string>",
          "model_id": "<string>",
          "model_selection": {
            "models": [
              "<string>"
            ],
            "sort": [
              {
                "metric": "SORT_METRIC_UNSPECIFIED",
                "direction": "SORT_DIRECTION_UNSPECIFIED"
              }
            ],
            "ignore": [
              "<string>"
            ],
            "provider": {
              "order": [
                "<string>"
              ],
              "allow_fallbacks": true
            }
          },
          "text_generation_config": {
            "max_tokens": 123,
            "top_p": 123,
            "temperature": 123,
            "repetition_penalty": 123,
            "frequency_penalty": 123,
            "presence_penalty": 123,
            "stop_sequences": [
              "<string>"
            ],
            "seed": 123,
            "logit_bias": [
              {
                "token_id": "<string>",
                "bias_value": 123
              }
            ],
            "reasoning": {
              "effort": "unspecified",
              "max_tokens": 123,
              "exclude": true
            }
          },
          "message_templates": [
            {
              "role": "<string>",
              "content": "<string>",
              "content_items": [
                {
                  "text": "<string>"
                }
              ],
              "tool_calls": [
                {
                  "id": "<string>",
                  "name": "<string>",
                  "args": "<string>"
                }
              ],
              "tool_call_id": "<string>"
            }
          ]
        },
        "weight": 123
      }
    ]
  },
  "defaults": {
    "message_templates": [
      {
        "role": "<string>",
        "content": "<string>",
        "content_items": [
          {
            "text": "<string>"
          }
        ],
        "tool_calls": [
          {
            "id": "<string>",
            "name": "<string>",
            "args": "<string>"
          }
        ],
        "tool_call_id": "<string>"
      }
    ],
    "text_generation_config": {
      "max_tokens": 123,
      "top_p": 123,
      "temperature": 123,
      "repetition_penalty": 123,
      "frequency_penalty": 123,
      "presence_penalty": 123,
      "stop_sequences": [
        "<string>"
      ],
      "seed": 123,
      "logit_bias": [
        {
          "token_id": "<string>",
          "bias_value": 123
        }
      ],
      "reasoning": {
        "effort": "unspecified",
        "max_tokens": 123,
        "exclude": true
      }
    }
  }
}

Authorizations

​
Authorization
string
header
required

Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY.

Please make sure your API Key has write permissions for the Router API in order to create, update, and delete routers.

Path Parameters

​
router_id
string
required

Router ID.

Response

A successful response.

Route Evaluation: Routes are evaluated in order based on CEL conditions. The first route whose condition evaluates to true is selected. If no route matches, the defaultRoute is used. If defaultRoute is not set and no conditional routes match, the API returns an error: "No route matched. Configure a default route or adjust conditions."

Variant Selection: Within the selected route, a variant is chosen based on weights. Weights must sum to exactly 100 within each route (they are not normalized). Each route's variants are weighted independently - weights are not shared across routes.

​
name
string
required

Unique ID of router. Cannot be edited after creation.

Used to call this router in the Chat Completions API by setting the model parameter to inworld/<router-name>.

​
displayName
string

Router display name.

​
routes
object[]

List of conditional routes evaluated in order. Routes are checked sequentially, and the first route whose CEL condition evaluates to true is selected. Within the selected route, a variant is chosen based on weights (which must sum to 100 within that route).

​
defaultRoute
object

Default route used when no route matches. Optional, but if omitted and no routes match, requests will fail with error: "No route matched. Configure a default route or adjust conditions."

​
defaults
object

Configuration defaults for the router.