Router Management
List routers
List routers available to your API key.
/router/v1/routersAuthorizationstringrequired
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. You can create a key in one command with the Inworld CLI: inworld workspace add-key.
page_sizeinteger
The maximum number of routers to return.
page_tokenstring
A page token, received from a previous ListRouters call.
routersobject[]
The list of routers.
Show child attributes
namestringrequired
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>.
displayNamestring
Router display name.
routesobject[]
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
routeobjectrequired
Route configuration containing route ID and variants.
Show child attributes
route_idstringrequired
Unique identifier for this route (must be unique within the router).
variantsobject[]required
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
variantobjectrequired
A variant within a route specifying the model to use.
Show child attributes
variant_idstringrequired
Unique identifier for this variant (must be unique within the route).
model_idstring
The model to use, which can be:
- A model id (e.g.,
gpt-oss-120b). 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). This specifies the provider and model to use. autofor automatic model selection based on criteria like price, latency, or intelligence
model_selectionobject
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
modelsstring[]
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).
sortobject[]
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.
Show child attributes
metricenum<string>requireddefault: "SORT_METRIC_UNSPECIFIED"
Sort metric for model selection.
Available options:SORT_METRIC_UNSPECIFIEDSORT_METRIC_PRICESORT_METRIC_LATENCYSORT_METRIC_THROUGHPUTSORT_METRIC_INTELLIGENCESORT_METRIC_MATHSORT_METRIC_CODING
directionenum<string>default: "SORT_DIRECTION_UNSPECIFIED"
Sort direction for ordering.
Available options:SORT_DIRECTION_UNSPECIFIEDSORT_DIRECTION_ASCENDINGSORT_DIRECTION_DESCENDING
ignorestring[]
Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai".
providerobject
Provider routing configuration. Use when model_id is specified without a provider prefix (e.g., gpt-oss-120b) to control which providers are tried and in what order.
Show child attributes
orderstring[]
Explicit list of providers to try, in order. Example: ["groq", "fireworks"]. When specified, providers are tried in this exact order (sort criteria will be ignored).
allow_fallbacksbooleandefault: true
Whether to allow falling back to the next provider if the current one fails. Defaults to true.
text_generation_configobject
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, if the default text generation configuration is {maxtokens: 100}, and the variant has a text generation configuration of {temperature: 0.9}, the variant will only pass {temperature: 0.9} to the model (and will not set maxtokens to 100).
Show child attributes
max_tokensinteger
Maximum number of tokens to generate.
top_pnumber
Top-p for generation.
temperaturenumber
Temperature for generation.
repetition_penaltynumber
Repetition penalty.
frequency_penaltynumber
Frequency penalty.
presence_penaltynumber
Presence penalty.
stop_sequencesstring[]
Stop sequences.
seedinteger
Random seed for generation.
logit_biasobject[]
Logit bias for token modification.
Show child attributes
token_idstringrequired
Token ID to apply bias to.
bias_valueintegerrequired
Bias value to apply to the token.
reasoningobject
Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
Show child attributes
effortenum<string>
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
max_tokensinteger
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.
excludeboolean
Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).
message_templatesobject[]
Message templates for this variant.
Show child attributes
rolestringrequired
Message role: system, user, assistant (and tool when applicable).
contentstring
Text content for text-only messages.
content_itemsoneOf[]
Content items for multimodal messages (text + images). If not empty, this takes precedence over content.
tool_callsobject[]
Tool calls generated by the model.
Show child attributes
idstringrequired
ID of the tool call.
typeenum<string>required
The type of the tool call. Always 'function'.
Available options:function
functionobjectrequired
The function that the model called.
Show child attributes
namestringrequired
The name of the function to call.
argumentsstringrequired
The arguments to call the function with, as a JSON string.
tool_call_idstring
Tool call ID this message is responding to (for tool role).
web_searchobject
Enable tool-based web search grounding for this variant. When the selected variant has web search enabled, the tool-based flow activates automatically for that request. See Web Search for details.
Show child attributes
engineenum<string>default: "exa"
Search backend. Valid values are exa and google.
Available options:exagoogle
max_resultsintegerdefault: 3
Search results per search call.
max_stepsintegerdefault: 1
Maximum search/refine rounds.
weightnumberrequired
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.
conditionobjectrequired
A single condition rule to evaluate against the request context.
Show child attributes
cel_expressionstringrequired
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.
defaultRouteobject
Route configuration containing route ID and variants.
Show child attributes
route_idstringrequired
Unique identifier for this route (must be unique within the router).
variantsobject[]required
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
variantobjectrequired
A variant within a route specifying the model to use.
Show child attributes
variant_idstringrequired
Unique identifier for this variant (must be unique within the route).
model_idstring
The model to use, which can be:
- A model id (e.g.,
gpt-oss-120b). 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). This specifies the provider and model to use. autofor automatic model selection based on criteria like price, latency, or intelligence
model_selectionobject
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
modelsstring[]
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).
sortobject[]
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.
Show child attributes
metricenum<string>requireddefault: "SORT_METRIC_UNSPECIFIED"
Sort metric for model selection.
Available options:SORT_METRIC_UNSPECIFIEDSORT_METRIC_PRICESORT_METRIC_LATENCYSORT_METRIC_THROUGHPUTSORT_METRIC_INTELLIGENCESORT_METRIC_MATHSORT_METRIC_CODING
directionenum<string>default: "SORT_DIRECTION_UNSPECIFIED"
Sort direction for ordering.
Available options:SORT_DIRECTION_UNSPECIFIEDSORT_DIRECTION_ASCENDINGSORT_DIRECTION_DESCENDING
ignorestring[]
Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai".
providerobject
Provider routing configuration. Use when model_id is specified without a provider prefix (e.g., gpt-oss-120b) to control which providers are tried and in what order.
Show child attributes
orderstring[]
Explicit list of providers to try, in order. Example: ["groq", "fireworks"]. When specified, providers are tried in this exact order (sort criteria will be ignored).
allow_fallbacksbooleandefault: true
Whether to allow falling back to the next provider if the current one fails. Defaults to true.
text_generation_configobject
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, if the default text generation configuration is {maxtokens: 100}, and the variant has a text generation configuration of {temperature: 0.9}, the variant will only pass {temperature: 0.9} to the model (and will not set maxtokens to 100).
Show child attributes
max_tokensinteger
Maximum number of tokens to generate.
top_pnumber
Top-p for generation.
temperaturenumber
Temperature for generation.
repetition_penaltynumber
Repetition penalty.
frequency_penaltynumber
Frequency penalty.
presence_penaltynumber
Presence penalty.
stop_sequencesstring[]
Stop sequences.
seedinteger
Random seed for generation.
logit_biasobject[]
Logit bias for token modification.
Show child attributes
token_idstringrequired
Token ID to apply bias to.
bias_valueintegerrequired
Bias value to apply to the token.
reasoningobject
Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
Show child attributes
effortenum<string>
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
max_tokensinteger
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.
excludeboolean
Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).
message_templatesobject[]
Message templates for this variant.
Show child attributes
rolestringrequired
Message role: system, user, assistant (and tool when applicable).
contentstring
Text content for text-only messages.
content_itemsoneOf[]
Content items for multimodal messages (text + images). If not empty, this takes precedence over content.
tool_callsobject[]
Tool calls generated by the model.
Show child attributes
idstringrequired
ID of the tool call.
typeenum<string>required
The type of the tool call. Always 'function'.
Available options:function
functionobjectrequired
The function that the model called.
Show child attributes
namestringrequired
The name of the function to call.
argumentsstringrequired
The arguments to call the function with, as a JSON string.
tool_call_idstring
Tool call ID this message is responding to (for tool role).
web_searchobject
Enable tool-based web search grounding for this variant. When the selected variant has web search enabled, the tool-based flow activates automatically for that request. See Web Search for details.
Show child attributes
engineenum<string>default: "exa"
Search backend. Valid values are exa and google.
Available options:exagoogle
max_resultsintegerdefault: 3
Search results per search call.
max_stepsintegerdefault: 1
Maximum search/refine rounds.
weightnumberrequired
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.
defaultsobject
Configuration defaults for the router.
Show child attributes
message_templatesobject[]
Message templates for the router.
Show child attributes
rolestringrequired
Message role: system, user, assistant (and tool when applicable).
contentstring
Text content for text-only messages.
content_itemsoneOf[]
Content items for multimodal messages (text + images). If not empty, this takes precedence over content.
tool_callsobject[]
Tool calls generated by the model.
Show child attributes
idstringrequired
ID of the tool call.
typeenum<string>required
The type of the tool call. Always 'function'.
Available options:function
functionobjectrequired
The function that the model called.
Show child attributes
namestringrequired
The name of the function to call.
argumentsstringrequired
The arguments to call the function with, as a JSON string.
tool_call_idstring
Tool call ID this message is responding to (for tool role).
text_generation_configobject
Text generation configuration that will be applied to all variants that do not text generation configuration specified
Show child attributes
max_tokensinteger
Maximum number of tokens to generate.
top_pnumber
Top-p for generation.
temperaturenumber
Temperature for generation.
repetition_penaltynumber
Repetition penalty.
frequency_penaltynumber
Frequency penalty.
presence_penaltynumber
Presence penalty.
stop_sequencesstring[]
Stop sequences.
seedinteger
Random seed for generation.
logit_biasobject[]
Logit bias for token modification.
Show child attributes
token_idstringrequired
Token ID to apply bias to.
bias_valueintegerrequired
Bias value to apply to the token.
reasoningobject
Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
Show child attributes
effortenum<string>
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
max_tokensinteger
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.
excludeboolean
Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).
next_page_tokenstring
A token to retrieve the next page of results.