Router Management
Update router
Update an existing router (returns a long-running operation).
/router/v1/routers/{router_id}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>.
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).
Show child attributes
Route configuration containing route ID and variants.
Show child attributes
Weighted variants within this route. When this route is selected (based on its CEL condition), a variant is chosen based on weights. Weights must sum to exactly 100 within this route - they are not normalized and are independent of weights in other routes.
Show child attributes
A variant within a route specifying the model to use.
Show child attributes
The model to use, which can be:
- A model id (e.g.,
deepseek-v4-flash). The best provider is automatically selected by latency, or you can control provider selection viamodel_selection.provider. See Models for available models. - A provider-prefixed model id (e.g.,
openai/gpt-5.4). This specifies the provider and model to use. autofor automatic model selection based on criteria like price, latency, or intelligence
Configuration for model selection behavior: For specific modelid, defines fallback models if primary fails. For modelid "auto", defines candidate models and selection criteria.
Show child attributes
Optional list of model IDs for fallback or candidate selection. Behavior depends on modelid in the route: When modelid has provider (e.g., "openai/gpt-4o"): fallback models to try on failure. When model_id is "auto": candidate models to select from (or all available if not specified).
Optional composite sorting criteria. Must be an array of SortCriteria objects with metric field (e.g., [{"metric": "SORTMETRICPRICE"}, {"metric": "SORTMETRICLATENCY"}]). String arrays like ["price", "latency"] are NOT supported in router configuration.
Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai".
Provider routing configuration. Use when model_id is specified without a provider prefix (e.g., deepseek-v4-flash) to control which providers are tried and in what order.
Show child attributes
Explicit list of providers to try, in order. Example: ["groq", "deepinfra"]. When specified, providers are tried in this exact order (sort criteria will be ignored), and providers not in the list are not used.
Text generation parameters (temperature, max_tokens, etc.) for this variant. If set, this entire text generation configuration will be used instead of any default text generation configuration specified.
For example, suppose the default text generation configuration is {maxtokens: 100} and the variant sets {temperature: 0.9}. The variant passes only {temperature: 0.9} to the model. It does not set maxtokens to 100.
Show child attributes
Logit bias for token modification.
Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
Show child attributes
Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.
Available options:unspecifiednoneminimallowmediumhighxhigh
Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.
Message templates for this variant.
Show child attributes
Content items for multimodal messages (text + images). If not empty, this takes precedence over content.
Tool calls generated by the model.
Show child attributes
Web search configuration, at the top level or in extra_body. With a router-run engine, the model calls a search tool in a loop and the router returns a grounded answer; native uses the provider's built-in search. See Web search.
Proportion of traffic to route to this variant within its route. Weights must sum to exactly 100 within each route - they are not normalized. For example, if a route has two variants with weights 70 and 30, they will receive 70% and 30% of traffic respectively. Weights are independent per route - a weight of 70 in one route does not relate to weights in other routes.
A single condition rule to evaluate against the request context.
Show child attributes
Common Expression Language (CEL) expression evaluated against request metadata and messages. Routes are evaluated in order, and the first route whose cel_expression evaluates to true is selected.
See Conditional Routing for supported operations and additional details.
Route configuration containing route ID and variants.
Show child attributes
Weighted variants within this route. When this route is selected (based on its CEL condition), a variant is chosen based on weights. Weights must sum to exactly 100 within this route - they are not normalized and are independent of weights in other routes.
Show child attributes
A variant within a route specifying the model to use.
Show child attributes
The model to use, which can be:
- A model id (e.g.,
deepseek-v4-flash). The best provider is automatically selected by latency, or you can control provider selection viamodel_selection.provider. See Models for available models. - A provider-prefixed model id (e.g.,
openai/gpt-5.4). This specifies the provider and model to use. autofor automatic model selection based on criteria like price, latency, or intelligence
Configuration for model selection behavior: For specific modelid, defines fallback models if primary fails. For modelid "auto", defines candidate models and selection criteria.
Show child attributes
Optional list of model IDs for fallback or candidate selection. Behavior depends on modelid in the route: When modelid has provider (e.g., "openai/gpt-4o"): fallback models to try on failure. When model_id is "auto": candidate models to select from (or all available if not specified).
Optional composite sorting criteria. Must be an array of SortCriteria objects with metric field (e.g., [{"metric": "SORTMETRICPRICE"}, {"metric": "SORTMETRICLATENCY"}]). String arrays like ["price", "latency"] are NOT supported in router configuration.
Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai".
Provider routing configuration. Use when model_id is specified without a provider prefix (e.g., deepseek-v4-flash) to control which providers are tried and in what order.
Show child attributes
Explicit list of providers to try, in order. Example: ["groq", "deepinfra"]. When specified, providers are tried in this exact order (sort criteria will be ignored), and providers not in the list are not used.
Text generation parameters (temperature, max_tokens, etc.) for this variant. If set, this entire text generation configuration will be used instead of any default text generation configuration specified.
For example, suppose the default text generation configuration is {maxtokens: 100} and the variant sets {temperature: 0.9}. The variant passes only {temperature: 0.9} to the model. It does not set maxtokens to 100.
Show child attributes
Logit bias for token modification.
Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
Show child attributes
Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.
Available options:unspecifiednoneminimallowmediumhighxhigh
Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.
Message templates for this variant.
Show child attributes
Content items for multimodal messages (text + images). If not empty, this takes precedence over content.
Tool calls generated by the model.
Show child attributes
Web search configuration, at the top level or in extra_body. With a router-run engine, the model calls a search tool in a loop and the router returns a grounded answer; native uses the provider's built-in search. See Web search.
Proportion of traffic to route to this variant within its route. Weights must sum to exactly 100 within each route - they are not normalized. For example, if a route has two variants with weights 70 and 30, they will receive 70% and 30% of traffic respectively. Weights are independent per route - a weight of 70 in one route does not relate to weights in other routes.
Configuration defaults for the router.
Show child attributes
Message templates for the router.
Show child attributes
Content items for multimodal messages (text + images). If not empty, this takes precedence over content.
Tool calls generated by the model.
Show child attributes
Text generation configuration that will be applied to all variants that do not text generation configuration specified
Show child attributes
Logit bias for token modification.
Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
Show child attributes
Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.
Available options:unspecifiednoneminimallowmediumhighxhigh
Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.
Service-defined metadata for the operation (type varies).
The error result of the operation (if any).