--- title: "Update router" method: PATCH path: "/router/v1/routers/{router_id}" tags: ["Router Management"] --- # Update router `PATCH /router/v1/routers/{router_id}` Update an existing router. Returns a long-running operation (LRO). ## Path parameters - `router_id` string, required ## Query parameters - `update_mask` string ## Request body - Router — **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. 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. - `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. - `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. - `metric` 'SORT_METRIC_UNSPECIFIED' | 'SORT_METRIC_PRICE' | 'SORT_METRIC_LATENCY' | 'SORT_METRIC_THROUGHPUT' | 'SORT_METRIC_INTELLIGENCE' | 'SORT_METRIC_MATH' | 'SORT_METRIC_CODING', required — Sort metric for model selection. - `direction` 'SORT_DIRECTION_UNSPECIFIED' | 'SORT_DIRECTION_ASCENDING' | 'SORT_DIRECTION_DESCENDING' — Sort direction for ordering. - `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. - `order` string[] — 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_fallbacks` boolean — Whether to allow falling back to the next provider if the current one fails. Defaults to true. - `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). - `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`. - union — Deprecated. Use ContentPart instead. - … - `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. - … - `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 - `text` string, required — Text content. - object - `image` ImageUrl, required — Image URL or base64 data URI with optional detail level. - … - `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). ## Response `200` A successful response. Returns a long-running operation (LRO). - LongrunningOperation — 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). - `@type` string - `done` boolean — If true, the operation has completed. - `error` object — The error result of the operation (if any). - `code` integer - `message` string - `details` object[] - `response` object — The normal response of the operation (if any). ## Other responses - `401` — Unauthorized - Invalid or missing API key --- [API](https://skmtc.net/inworld/apis/inworld-text-to-speech-api.md) · [All operations](https://skmtc.net/inworld/apis/inworld-text-to-speech-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/inworld/inworld-text-to-speech-api/versions/e79009799a0d/schema)