Skip to main content
POST
/
router
/
v1
/
routers
Create router
curl --request POST \
  --url https://api.inworld.ai/router/v1/routers \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "routers/example-router",
  "displayName": "Example Router",
  "defaults": {
    "message_templates": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      }
    ]
  },
  "routes": [
    {
      "route": {
        "route_id": "support",
        "variants": [
          {
            "variant": {
              "variant_id": "primary",
              "model_id": "openai/gpt-4o"
            },
            "weight": 100
          }
        ]
      },
      "condition": {
        "cel_expression": "use_case == 'support'"
      }
    }
  ],
  "defaultRoute": {
    "route_id": "default",
    "variants": [
      {
        "variant": {
          "variant_id": "default",
          "model_id": "openai/gpt-4o-mini"
        },
        "weight": 100
      }
    ]
  }
}
EOF
{
  "name": "<string>",
  "metadata": {
    "@type": "<string>"
  },
  "done": true,
  "error": {
    "code": 123,
    "message": "<string>",
    "details": [
      {}
    ]
  },
  "response": {}
}
Create a router that can be used with the chat completions endpoint. Returns a long-running operation. See Router documentation for more details.

Authorizations

​
Authorization
string
header
required

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

Body

application/json

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.

​
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.

Response

A successful response. Returns a long-running operation (LRO).

A long-running operation (LRO). Poll until done is true.

​
name
string

The server-assigned operation name.

​
metadata
object

Service-defined metadata for the operation (type varies).

​
done
boolean

If true, the operation has completed.

​
error
object

The error result of the operation (if any).

​
response
object

The normal response of the operation (if any).