Capabilities

Conditional Routing

Route requests based on CEL expressions and request metadata

Conditional routing allows you to route requests to different models based on conditions that evaluate request metadata.

You can use conditional routing to:

Segment by user tier — route premium users to flagship models and free users to cost-effective ones.
Route by geography — direct requests to different models based on geography.
Optimize by complexity — send simple prompts to fast, cheap models and complex ones to high-capability models.

Basic Structure

Routes are defined directly on the Router. Each route has a route object and a condition object.

Example router set up

json

{
  "name": "routers/my-router",
  "routes": [
    {
      "route": {
        "route_id": "premium-tier",
        "variants": [
          {
            "variant": {
              "variant_id": "premium-gpt5",
              "model_id": "openai/gpt-5.2"
            },
            "weight": 100
          }
        ]
      },
      "condition": {
        "cel_expression": "tier == \"premium\""
      }
    },
    {
      "route": {
        "route_id": "free-tier",
        "variants": [
          {
            "variant": {
              "variant_id": "free-flash",
              "model_id": "google-ai-studio/gemini-2.5-flash"
            },
            "weight": 100
          }
        ]
      },
      "condition": {
        "cel_expression": "tier == \"free\""
      }
    }
  ],
  "defaultRoute": {
    "route_id": "default",
    "variants": [
      {
        "variant": {
          "variant_id": "default-variant",
          "model_id": "google-ai-studio/gemini-2.5-flash"
        },
        "weight": 100
      }
    ]
  }
}

The condition field accepts a CEL expression that can be evaluated against the following from each Chat Completions request:

Request metadata — key-value pairs sent in extra_body.metadata (e.g. user tier, region, complexity score).
Messages — the full messages array from the request body

Routes are evaluated in order, and the first route whose condition evaluates to true is selected.

The table below lists the available operations for constructing a CEL expression:

Operation	Example	Description
Equality	`tier == "premium"`	Matches a specific value.
Comparison	`request_count > 100`	Numeric comparisons (`>`, `<`, `>=`, `<=`).
Logical AND	`tier == "premium" && region == "us-east"`	Both conditions must be true.
Logical OR	`tier == "premium" \|\| tier == "enterprise"`	Either condition must be true.
Range check	`score >= 80 && score <= 100`	Matches values within a range.
`startsWith()`	`user_id.startsWith("enterprise-")`	Checks if a string starts with a prefix.
`endsWith()`	`user_id.endsWith("-admin")`	Checks if a string ends with a suffix.
`contains()`	`user_id.contains("test")`	Checks if a string contains a substring.
`matches()`	`messages.last().content.matches("(?i).\\bcode\\b.")`	RE2 regex match on any string field.
`size()`	`user_id.size() > 10`	Gets the length of a string.
`messages.has()`	`messages.has()`	`true` if the message array exists and is non-empty.
`messages.first()`	`messages.first().content.contains("system")`	First message in the array.
`messages.last()`	`messages.last().content.matches("(?i).help.")`	Last message in the array.
`messages.get(i)`	`messages.get(0).role == "system"`	Message at index `i` (0-based).
`messages.len()`	`messages.len() > 3`	Number of messages in the array.

Expressions are typed — ensure your metadata types match. Use count == 100 when the value is a number and tier == "premium" when it's a string. Mismatched types will not match.

Making a Request

When calling your router, pass metadata in your requests using extra_body.metadata to provide the values referenced by your conditions, enabling dynamic route selection.

bash

curl --request POST \
  --url https://api.inworld.ai/v1/chat/completions \
  --header 'Authorization: Basic <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "inworld/my-router",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "extra_body": {
      "metadata": {
        "tier": "premium",
        "user_id": "user-123",
        "region": "us-east"
      }
    }
  }'

In this example, the provided metadata (tier, user_id, and region) will be available for the router’s CEL expressions, enabling conditional routes to match and select the appropriate model configuration based on those values.

Example Use Cases

User Subscription Tiers

Route users to different models based on their subscription tier:

json

{
  "cel_expression": "subscription_tier == \"pro\""
}

Geographic Routing

Route requests based on user location:

json

{
  "cel_expression": "region == \"eu\""
}

Prompt-Based Routing

You can combine fast prompt-based regex routing with metadata checks in a single condition, enabling routing by both what the user is asking and who the user is.

Route coding questions from premium users to a reasoning model:

json

{
  "cel_expression": "messages.last().content.matches(\"(?i).*\\\\b(code|debug|refactor|bug fix)\\\\b.*\") && tier == \"premium\""
}

Regex also works on metadata fields (e.g. user_id.matches(".*-admin$")) and on any message — use messages.first() to match the first message or messages.get(i) for a specific turn.

Route translation requests to a multilingual model:

json

{
  "cel_expression": "messages.last().content.matches(\"(?i).*\\\\btranslat(e|ion)\\\\b.*\")"
}

Route long conversations (e.g. 10+ turns) to a model with a large context window:

json

{
  "cel_expression": "messages.len() > 10"
}

Conditions are evaluated before route variants are selected, so messages defined inside variants are not part of condition evaluation.

Dynamic Tiering

Route requests to different model tiers based on prompt complexity. Use a lightweight classifier in your application to score complexity, then let the router pick the right model:

json

{
  "routes": [
    {
      "route": {
        "route_id": "complex",
        "variants": [
          {
            "variant": { "variant_id": "gpt5-premium", "model_id": "openai/gpt-5.2" },
            "weight": 100
          }
        ]
      },
      "condition": {
        "cel_expression": "complexity_score >= 8"
      }
    },
    {
      "route": {
        "route_id": "standard",
        "variants": [
          {
            "variant": { "variant_id": "gpt5", "model_id": "openai/gpt-5-mini" },
            "weight": 100
          }
        ]
      },
      "condition": {
        "cel_expression": "complexity_score >= 4"
      }
    }
  ],
  "defaultRoute": {
    "route_id": "simple",
    "variants": [
      {
            "variant": { "variant_id": "flash", "model_id": "openai/gpt-5-nano" },
        "weight": 100
      }
    ]
  }
}

Simple tasks go to fast, cheap models while complex tasks get flagship models — optimizing cost without sacrificing quality where it matters.