--- title: "List routers" method: GET path: "/router/v1/routers" tags: ["Router Management"] --- # List routers `GET /router/v1/routers` ## Request - Base URL: `https://api.inworld.ai` - URL: `https://api.inworld.ai/router/v1/routers` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) List routers available to your API key. ## Query parameters - `page_size` integer - `page_token` string ## Response `200` A successful response. - ListRoutersResponse - `routers` Router[]: The list of routers. - `name` string, required: Unique ID of router. Cannot be edited after creation. Used to call this router in the [Chat Completions](/api-reference/routerAPI/chat-completions) API by setting the `model` parameter to `inworld/`. - `displayName` string: Router display name. - `routes` ConditionalRoute[]: 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). - `route` Route, required: Route configuration containing route ID and variants. - `route_id` string, required: Unique identifier for this route (must be unique within the router). - `variants` WeightedVariant[], 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. - `variant` Variant, required: A variant within a route specifying the model to use. - `variant_id` string, required: Unique identifier for this variant (must be unique within the route). - `model_id` string: The model to use, which can be: - A model id (e.g., `gpt-oss-120b`). The best provider is [automatically selected](/router/usage/specific-model#provider-routing) by latency, or you can control provider selection via `model_selection.provider`. See [Models](/api-reference/modelsAPI/modelservice/list-models) for available models. - A provider-prefixed model id (e.g., `openai/gpt-5`). This specifies the provider and model to use. - `auto` for automatic model selection based on criteria like price, latency, or intelligence - `model_selection` ModelSelection: LLM routing configuration for model selection and fallback. - … - `text_generation_config` TextGenerationConfig: Text generation configuration that will be applied to all variants that do not text generation configuration specified - … - `message_templates` MessageTemplate[]: Message templates for this variant. - … - `web_search` WebSearchConfig: Web search configuration (under `extra_body`). The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer. See [Web search](/router/capabilities/web-search). - … - `weight` number, float, required: 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. - `condition` Condition, required: A single condition rule to evaluate against the request context. - `cel_expression` string, required: 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](/router/capabilities/conditional-routing) for supported operations and additional details. - `defaultRoute` Route: Route configuration containing route ID and variants. - `route_id` string, required: Unique identifier for this route (must be unique within the router). - `variants` WeightedVariant[], 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. - `variant` Variant, required: A variant within a route specifying the model to use. - `variant_id` string, required: Unique identifier for this variant (must be unique within the route). - `model_id` string: The model to use, which can be: - A model id (e.g., `gpt-oss-120b`). The best provider is [automatically selected](/router/usage/specific-model#provider-routing) by latency, or you can control provider selection via `model_selection.provider`. See [Models](/api-reference/modelsAPI/modelservice/list-models) for available models. - A provider-prefixed model id (e.g., `openai/gpt-5`). This specifies the provider and model to use. - `auto` for automatic model selection based on criteria like price, latency, or intelligence - `model_selection` ModelSelection: LLM routing configuration for model selection and fallback. - `models` string[]: Optional list of model IDs for fallback or candidate selection. Behavior depends on model_id in the route: When model_id 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). - `sort` SortCriteria[]: Optional composite sorting criteria. Must be an array of SortCriteria objects with `metric` field (e.g., [{"metric": "SORT_METRIC_PRICE"}, {"metric": "SORT_METRIC_LATENCY"}]). String arrays like ["price", "latency"] are NOT supported in router configuration. - … - `ignore` string[]: Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai". - `provider` ProviderConfig: Configuration for provider-level routing when using a model without a provider prefix. - … - `text_generation_config` TextGenerationConfig: Text generation configuration that will be applied to all variants that do not text generation configuration specified - `max_tokens` integer: Maximum number of tokens to generate. - `top_p` number, float: Top-p for generation. - `temperature` number, float: Temperature for generation. - `repetition_penalty` number, float: Repetition penalty. - `frequency_penalty` number, float: Frequency penalty. - `presence_penalty` number, float: Presence penalty. - `stop_sequences` string[]: Stop sequences. - `seed` integer: Random seed for generation. - `logit_bias` LogitBias[]: Logit bias for token modification. - … - `reasoning` ReasoningConfig: Reasoning configuration for models that support chain-of-thought reasoning. Provides a unified interface across different providers (OpenAI, Anthropic, Google, Groq, etc.). - … - `message_templates` MessageTemplate[]: Message templates for this variant. - `role` string, required: Message role: `system`, `user`, `assistant` (and `tool` when applicable). - `content` string: Text content for text-only messages. - `content_items` ContentItem[]: Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`. - … - `tool_calls` ToolCall[]: Tool calls generated by the model. - … - `tool_call_id` string: Tool call ID this message is responding to (for `tool` role). - `web_search` WebSearchConfig: Web search configuration (under `extra_body`). The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer. See [Web search](/router/capabilities/web-search). - `engine` 'exa' | 'google': Search backend. Valid values are `exa` and `google`. - `max_results` integer: Search results per search call. - `max_steps` integer: Maximum search/refine rounds. - `weight` number, float, required: 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. - `defaults` RouterDefaults: Configuration defaults for the router. - `message_templates` MessageTemplate[]: Message templates for the router. - `role` string, required: Message role: `system`, `user`, `assistant` (and `tool` when applicable). - `content` string: Text content for text-only messages. - `content_items` ContentItem[]: Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`. - union: Deprecated. Use ContentPart instead. - object - … - object - … - `tool_calls` ToolCall[]: Tool calls generated by the model. - `id` string, required: ID of the tool call. - `type` 'function', required: The type of the tool call. Always 'function'. - `function` object, required: The function that the model called. - `name` string, required: The name of the function to call. - `arguments` string, required: The arguments to call the function with, as a JSON string. - `tool_call_id` string: Tool call ID this message is responding to (for `tool` role). - `text_generation_config` TextGenerationConfig: Text generation configuration that will be applied to all variants that do not text generation configuration specified - `max_tokens` integer: Maximum number of tokens to generate. - `top_p` number, float: Top-p for generation. - `temperature` number, float: Temperature for generation. - `repetition_penalty` number, float: Repetition penalty. - `frequency_penalty` number, float: Frequency penalty. - `presence_penalty` number, float: Presence penalty. - `stop_sequences` string[]: Stop sequences. - `seed` integer: Random seed for generation. - `logit_bias` LogitBias[]: Logit bias for token modification. - `token_id` string, required: Token ID to apply bias to. - `bias_value` integer, required: Bias value to apply to the token. - `reasoning` ReasoningConfig: Reasoning configuration for models that support chain-of-thought reasoning. Provides a unified interface across different providers (OpenAI, Anthropic, Google, Groq, etc.). - `effort` 'unspecified' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh': 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%. - `max_tokens` integer: 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. - `exclude` boolean: 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_token` string: A token to retrieve the next page of results. ## Other responses - `401`: Unauthorized - Invalid or missing API key --- [API](https://skmtc.dev/inworld/apis/inworld-text-to-speech-api.md) - [All operations](https://skmtc.dev/inworld/apis/inworld-text-to-speech-api/llms.txt) - [OpenAPI document](https://skmtc.dev/inworld/apis/inworld-text-to-speech-api/revisions/e79009799a0d?raw)