> ## Documentation Index > Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt > Use this file to discover all available pages before exploring further. # List routers > List routers available to your API key. ## OpenAPI ````yaml get /router/v1/routers openapi: 3.0.0 info: title: Router API version: v1 description: >- Intelligent routing and optimization for LLM requests. Automatically selects the best model based on your criteria, handles fallbacks, and optimizes for cost, latency, or intelligence. Also includes a Router CRUD API for creating reusable routing configurations. servers: - url: https://api.inworld.ai description: Production server security: - inworld_basic: [] tags: - name: Chat Completions description: >- Main API endpoint for intelligent LLM routing and optimization. Generate chat completions with automatic model selection or specific models with fallbacks. - name: Moderations description: >- Classify text content for harmful material. Includes OpenAI-compatible moderation and conversation-aware chat moderation with AILuminate safety signals. - name: Router Management description: >- Service endpoints for creating and managing reusable router configurations. Use these to set up routing strategies that can be referenced in Chat Completions requests. paths: /router/v1/routers: get: tags: - Router Management summary: List routers description: List routers available to your API key. operationId: RouterService_ListRouters parameters: - name: page_size in: query required: false schema: type: integer format: int32 minimum: 0 description: The maximum number of routers to return. - name: page_token in: query required: false schema: type: string description: A page token, received from a previous `ListRouters` call. responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/ListRoutersResponse' '401': description: Unauthorized - Invalid or missing API key content: text/plain: schema: type: string example: Unauthorized x-codeSamples: - lang: bash label: cURL source: >- curl --location 'https://api.inworld.ai/router/v1/routers?page_size=10' \ --header "Authorization: Basic $INWORLD_API_KEY" - lang: python label: Python source: |- import os import requests url = "https://api.inworld.ai/router/v1/routers" headers = { "Authorization": f"Basic {os.getenv('INWORLD_API_KEY')}" } params = { "page_size": 10 } response = requests.get(url, headers=headers, params=params) print(response.json()) - lang: javascript label: JavaScript source: |- const url = 'https://api.inworld.ai/router/v1/routers?page_size=10'; const response = await fetch(url, { headers: { 'Authorization': `Basic ${process.env.INWORLD_API_KEY}`, }, }); const data = await response.json(); console.log(data); components: schemas: ListRoutersResponse: type: object properties: routers: type: array items: $ref: '#/components/schemas/Router' description: The list of routers. next_page_token: type: string description: A token to retrieve the next page of results. Router: type: object description: >- **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. properties: name: type: string description: >- 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: type: string description: Router display name. routes: type: array items: $ref: '#/components/schemas/ConditionalRoute' description: >- 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). defaultRoute: $ref: '#/components/schemas/Route' description: >- Default route used when no route matches. Optional, but if omitted and no routes match, requests will fail with error: "No route matched. Configure a default route or adjust conditions." defaults: $ref: '#/components/schemas/RouterDefaults' required: - name ConditionalRoute: type: object description: >- A route with a CEL condition for conditional routing. Routes are evaluated in order, and the first route whose condition evaluates to `true` is selected. Within the selected route, variants are chosen based on weights. properties: route: $ref: '#/components/schemas/Route' condition: $ref: '#/components/schemas/Condition' required: - route - condition Route: type: object description: Route configuration containing route ID and variants. properties: route_id: type: string description: Unique identifier for this route (must be unique within the router). variants: type: array items: $ref: '#/components/schemas/WeightedVariant' description: >- 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. required: - route_id - variants RouterDefaults: type: object description: Configuration defaults for the router. properties: message_templates: type: array items: $ref: '#/components/schemas/MessageTemplate' description: Message templates for the router. text_generation_config: $ref: '#/components/schemas/TextGenerationConfig' Condition: type: object description: A single condition rule to evaluate against the request context. properties: cel_expression: type: string description: >- 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. required: - cel_expression WeightedVariant: type: object description: A variant with weight for load balancing within a route. properties: variant: $ref: '#/components/schemas/Variant' weight: type: number format: float description: >- 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. required: - variant - weight MessageTemplate: type: object description: >- Message template represents a chat message in a conversation. For text-only messages, use `content`. For multimodal messages, use `content_items`. properties: role: type: string description: >- Message role: `system`, `user`, `assistant` (and `tool` when applicable). content: type: string description: Text content for text-only messages. content_items: type: array items: $ref: '#/components/schemas/ContentItem' description: >- Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`. tool_calls: type: array items: $ref: '#/components/schemas/ToolCall' description: Tool calls generated by the model. tool_call_id: type: string description: Tool call ID this message is responding to (for `tool` role). required: - role TextGenerationConfig: type: object description: >- Text generation configuration that will be applied to all variants that do not text generation configuration specified properties: max_tokens: type: integer format: int32 description: Maximum number of tokens to generate. top_p: type: number format: float description: Top-p for generation. temperature: type: number format: float description: Temperature for generation. repetition_penalty: type: number format: float description: Repetition penalty. frequency_penalty: type: number format: float description: Frequency penalty. presence_penalty: type: number format: float description: Presence penalty. stop_sequences: type: array items: type: string description: Stop sequences. seed: type: integer description: Random seed for generation. format: int32 logit_bias: type: array items: $ref: '#/components/schemas/LogitBias' description: Logit bias for token modification. reasoning: $ref: '#/components/schemas/ReasoningConfig' description: >- Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning. Variant: type: object description: A variant within a route specifying the model to use. properties: variant_id: type: string description: >- Unique identifier for this variant (must be unique within the route). model_id: type: string description: >- 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: $ref: '#/components/schemas/ModelSelection' description: >- Configuration for model selection behavior: For specific model_id, defines fallback models if primary fails. For model_id "auto", defines candidate models and selection criteria. text_generation_config: $ref: '#/components/schemas/TextGenerationConfig' description: >- 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 {max_tokens: 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 max_tokens to 100). message_templates: type: array items: $ref: '#/components/schemas/MessageTemplate' description: Message templates for this variant. web_search: $ref: '#/components/schemas/WebSearchConfig' description: >- 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](/router/capabilities/web-search) for details. required: - variant_id ContentItem: description: >- A single content item in a message. Only one of `text` or `image` should be set. oneOf: - type: object properties: text: type: string description: Text content. required: - text - type: object properties: image: $ref: '#/components/schemas/ImageUrl' required: - image ToolCall: type: object description: A tool call made by the model. properties: id: type: string description: ID of the tool call. name: type: string description: Name of the tool to call. args: type: string description: Arguments for the tool call. required: - id - name LogitBias: type: object description: Modifies the likelihood of specified tokens appearing in the completion. properties: token_id: type: string description: Token ID to apply bias to. bias_value: type: integer format: int32 description: Bias value to apply to the token. required: - token_id - bias_value ReasoningConfig: type: object description: >- Reasoning configuration for models that support chain-of-thought reasoning. Provides a unified interface across different providers (OpenAI, Anthropic, Google, Groq, etc.). properties: effort: type: string enum: - unspecified - none - minimal - low - medium - high - xhigh description: >- 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: type: integer format: int32 description: >- 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: type: boolean description: >- 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). ModelSelection: type: object description: LLM routing configuration for model selection and fallback. properties: models: type: array items: type: string description: >- 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: type: array items: $ref: '#/components/schemas/SortCriteria' description: >- 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: type: array items: type: string description: >- Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai". provider: $ref: '#/components/schemas/ProviderConfig' description: >- 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. WebSearchConfig: type: object description: >- 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). properties: engine: type: string enum: - exa - google default: exa description: Search backend. Valid values are `exa` and `google`. max_results: type: integer description: Search results per search call. default: 3 minimum: 1 max_steps: type: integer description: Maximum search/refine rounds. default: 1 minimum: 1 ImageUrl: type: object description: Image URI with detail level specification. properties: uri: type: string description: URI of the image. detail: $ref: '#/components/schemas/ImageDetail' required: - uri SortCriteria: type: object description: Single ordering criterion with metric and direction. properties: metric: $ref: '#/components/schemas/SortMetric' direction: $ref: '#/components/schemas/SortDirection' required: - metric ProviderConfig: type: object description: >- Configuration for provider-level routing when using a model without a provider prefix. properties: order: type: array items: type: string description: >- 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: type: boolean description: >- Whether to allow falling back to the next provider if the current one fails. Defaults to true. default: true ImageDetail: type: string description: Image detail level specification. enum: - IMAGE_DETAIL_UNSPECIFIED - IMAGE_DETAIL_AUTO - IMAGE_DETAIL_LOW - IMAGE_DETAIL_HIGH default: IMAGE_DETAIL_UNSPECIFIED SortMetric: type: string description: Sort metric for model selection. enum: - SORT_METRIC_UNSPECIFIED - SORT_METRIC_PRICE - SORT_METRIC_LATENCY - SORT_METRIC_THROUGHPUT - SORT_METRIC_INTELLIGENCE - SORT_METRIC_MATH - SORT_METRIC_CODING default: SORT_METRIC_UNSPECIFIED SortDirection: type: string description: Sort direction for ordering. enum: - SORT_DIRECTION_UNSPECIFIED - SORT_DIRECTION_ASCENDING - SORT_DIRECTION_DESCENDING default: SORT_DIRECTION_UNSPECIFIED securitySchemes: inworld_basic: type: apiKey in: header name: Authorization description: >- Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, please populate `Basic $INWORLD_API_KEY`. Please make sure your API Key has [write permissions for the Router API](/api-reference/introduction#getting-an-api-key) in order to create, update, and delete routers. ````