> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing Rules SDK Reference

> Manage AI Gateway routing rules with the Node.js and Python SDKs: list, create, retrieve, update, and delete rules and list the models they use.

## Routing Rules

### List Routing Rules

Returns routing rules ordered by ascending priority. Supports cursor pagination, search, status, project, and referenced-model filters.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.routing_rules.list(limit=10)

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.routingRules.list({
      limit: 10,
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[int],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "project_id": Optional[str],
        "search": Optional[str],
        "enabled": Optional[bool],
        "model": List[str],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
      projectId?: string;
      search?: string;
      enabled?: boolean;
      model?: string[];
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": [{
            "id": str,
            "created_at": str,
            "updated_at": str,
            "created_by_id": str,
            "updated_by_id": str,
            "project_id": str,
            "display_name": str,
            "description": str,
            "enabled": bool,
            "expression": {  # optional
                "config": Dict[str, Any],  # optional
                "cel": Optional[str],
            },
            "models_config": {  # optional
                "mode": Optional[str],
                "models": [{  # optional
                    "model": Optional[str],
                    "display_name": Optional[str],
                    "weight": Optional[float],
                    "integration_id": Optional[str],
                }],
            },
            "plugins": [{
                "id": Optional[str],
                "language": Optional[str],
                "entities": List[str],  # optional
                "on_failure": Optional[str],
                "threshold": Optional[float],
                "mask": List[str],  # optional
                "regions": List[str],  # optional
                "entity_thresholds": Dict[str, float],  # optional
            }],
            "priority": int,
            "cache_config": {  # optional
                "ttl": int,
            },
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        createdAt: Date;
        updatedAt: Date;
        createdById: string;
        updatedById: string;
        projectId: string;
        displayName: string;
        description: string;
        enabled: boolean;
        expression?: {
          config?: Record<string, unknown>;
          cel?: string;
        };
        modelsConfig?: {
          mode?: string;
          models?: {
            model?: string;
            displayName?: string;
            weight?: number;
            integrationId?: string;
          }[];
        };
        plugins: {
          id?: string;
          language?: string;
          entities?: string[];
          onFailure?: string;
          threshold?: number;
          mask?: string[];
          regions?: string[];
          entityThresholds?: Record<string, number>;
        }[];
        priority: number;
        cacheConfig?: {
          ttl: number;
        };
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Routing Rule

Creates a routing rule with metadata and optional model, plugin, priority, and matching configuration. Rules default to disabled when `enabled` is omitted.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.routing_rules.create(display_name="Route to Claude")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.routingRules.create({
      displayName: "Route to Claude",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "display_name": str,  # required
        "description": Optional[str],
        "project_id": Optional[str],
        "enabled": Optional[bool],
        "expression": {  # optional
            "config": Dict[str, Any],  # optional
            "cel": Optional[str],
        },
        "models_config": {  # optional
            "mode": Optional[str],
            "models": [{  # optional
                "model": Optional[str],
                "display_name": Optional[str],
                "weight": Optional[float],
                "integration_id": Optional[str],
            }],
        },
        "plugins": [{  # optional
            "id": Optional[str],
            "language": Optional[str],
            "entities": List[str],  # optional
            "on_failure": Optional[str],
            "threshold": Optional[float],
            "mask": List[str],  # optional
            "regions": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
        }],
        "priority": Optional[int],
        "cache_config": {  # optional
            "ttl": int,  # required
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      displayName: string;  // required
      description?: string;
      projectId?: string;
      enabled?: boolean;
      expression?: {
        config?: Record<string, unknown>;
        cel?: string;
      };
      modelsConfig?: {
        mode?: string;
        models?: {
          model?: string;
          displayName?: string;
          weight?: number;
          integrationId?: string;
        }[];
      };
      plugins?: {
        id?: string;
        language?: string;
        entities?: string[];
        onFailure?: string;
        threshold?: number;
        mask?: string[];
        regions?: string[];
        entityThresholds?: Record<string, number>;
      }[];
      priority?: number;
      cacheConfig?: {
        ttl: number;  // required
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "project_id": str,
        "display_name": str,
        "description": str,
        "enabled": bool,
        "expression": {  # optional
            "config": Dict[str, Any],  # optional
            "cel": Optional[str],
        },
        "models_config": {  # optional
            "mode": Optional[str],
            "models": [{  # optional
                "model": Optional[str],
                "display_name": Optional[str],
                "weight": Optional[float],
                "integration_id": Optional[str],
            }],
        },
        "plugins": [{
            "id": Optional[str],
            "language": Optional[str],
            "entities": List[str],  # optional
            "on_failure": Optional[str],
            "threshold": Optional[float],
            "mask": List[str],  # optional
            "regions": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
        }],
        "priority": int,
        "cache_config": {  # optional
            "ttl": int,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      createdAt: Date;
      updatedAt: Date;
      createdById: string;
      updatedById: string;
      projectId: string;
      displayName: string;
      description: string;
      enabled: boolean;
      expression?: {
        config?: Record<string, unknown>;
        cel?: string;
      };
      modelsConfig?: {
        mode?: string;
        models?: {
          model?: string;
          displayName?: string;
          weight?: number;
          integrationId?: string;
        }[];
      };
      plugins: {
        id?: string;
        language?: string;
        entities?: string[];
        onFailure?: string;
        threshold?: number;
        mask?: string[];
        regions?: string[];
        entityThresholds?: Record<string, number>;
      }[];
      priority: number;
      cacheConfig?: {
        ttl: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### List Used Models

Returns the distinct model references used by routing rules in the requested scope.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.routing_rules.list_used_models()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.routingRules.listUsedModels();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "project_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      projectId?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "models": List[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      models: string[];
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Routing Rule

Retrieves a routing rule by its unique identifier.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.routing_rules.retrieve(routing_rule_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.routingRules.retrieve({
      routingRuleId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "routing_rule_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      routingRuleId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "project_id": str,
        "display_name": str,
        "description": str,
        "enabled": bool,
        "expression": {  # optional
            "config": Dict[str, Any],  # optional
            "cel": Optional[str],
        },
        "models_config": {  # optional
            "mode": Optional[str],
            "models": [{  # optional
                "model": Optional[str],
                "display_name": Optional[str],
                "weight": Optional[float],
                "integration_id": Optional[str],
            }],
        },
        "plugins": [{
            "id": Optional[str],
            "language": Optional[str],
            "entities": List[str],  # optional
            "on_failure": Optional[str],
            "threshold": Optional[float],
            "mask": List[str],  # optional
            "regions": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
        }],
        "priority": int,
        "cache_config": {  # optional
            "ttl": int,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      createdAt: Date;
      updatedAt: Date;
      createdById: string;
      updatedById: string;
      projectId: string;
      displayName: string;
      description: string;
      enabled: boolean;
      expression?: {
        config?: Record<string, unknown>;
        cel?: string;
      };
      modelsConfig?: {
        mode?: string;
        models?: {
          model?: string;
          displayName?: string;
          weight?: number;
          integrationId?: string;
        }[];
      };
      plugins: {
        id?: string;
        language?: string;
        entities?: string[];
        onFailure?: string;
        threshold?: number;
        mask?: string[];
        regions?: string[];
        entityThresholds?: Record<string, number>;
      }[];
      priority: number;
      cacheConfig?: {
        ttl: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Routing Rule

Permanently deletes a routing rule.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.routing_rules.delete(routing_rule_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.routingRules.delete({
      routingRuleId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "routing_rule_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      routingRuleId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Routing Rule

Partially updates routing-rule metadata or configuration. Project scope is immutable.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.routing_rules.update(routing_rule_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.routingRules.update({
      routingRuleId: "<id>",
      updateRoutingRuleRequest: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "routing_rule_id": str,  # required
        "display_name": Optional[str],
        "description": Optional[str],
        "enabled": Optional[bool],
        "expression": {  # optional
            "config": Dict[str, Any],  # optional
            "cel": Optional[str],
        },
        "models_config": {  # optional
            "mode": Optional[str],
            "models": [{  # optional
                "model": Optional[str],
                "display_name": Optional[str],
                "weight": Optional[float],
                "integration_id": Optional[str],
            }],
        },
        "plugins": [{  # optional
            "id": Optional[str],
            "language": Optional[str],
            "entities": List[str],  # optional
            "on_failure": Optional[str],
            "threshold": Optional[float],
            "mask": List[str],  # optional
            "regions": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
        }],
        "priority": Optional[int],
        "cache_config": {  # optional
            "ttl": int,  # required
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      routingRuleId: string;  // required
      updateRoutingRuleRequest: {  // required
        displayName?: string;
        description?: string;
        enabled?: boolean;
        expression?: {
          config?: Record<string, unknown>;
          cel?: string;
        };
        modelsConfig?: {
          mode?: string;
          models?: {
            model?: string;
            displayName?: string;
            weight?: number;
            integrationId?: string;
          }[];
        };
        plugins?: {
          id?: string;
          language?: string;
          entities?: string[];
          onFailure?: string;
          threshold?: number;
          mask?: string[];
          regions?: string[];
          entityThresholds?: Record<string, number>;
        }[];
        priority?: number;
        cacheConfig?: {
          ttl: number;  // required
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "created_at": str,
        "updated_at": str,
        "created_by_id": str,
        "updated_by_id": str,
        "project_id": str,
        "display_name": str,
        "description": str,
        "enabled": bool,
        "expression": {  # optional
            "config": Dict[str, Any],  # optional
            "cel": Optional[str],
        },
        "models_config": {  # optional
            "mode": Optional[str],
            "models": [{  # optional
                "model": Optional[str],
                "display_name": Optional[str],
                "weight": Optional[float],
                "integration_id": Optional[str],
            }],
        },
        "plugins": [{
            "id": Optional[str],
            "language": Optional[str],
            "entities": List[str],  # optional
            "on_failure": Optional[str],
            "threshold": Optional[float],
            "mask": List[str],  # optional
            "regions": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
        }],
        "priority": int,
        "cache_config": {  # optional
            "ttl": int,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      createdAt: Date;
      updatedAt: Date;
      createdById: string;
      updatedById: string;
      projectId: string;
      displayName: string;
      description: string;
      enabled: boolean;
      expression?: {
        config?: Record<string, unknown>;
        cel?: string;
      };
      modelsConfig?: {
        mode?: string;
        models?: {
          model?: string;
          displayName?: string;
          weight?: number;
          integrationId?: string;
        }[];
      };
      plugins: {
        id?: string;
        language?: string;
        entities?: string[];
        onFailure?: string;
        threshold?: number;
        mask?: string[];
        regions?: string[];
        entityThresholds?: Record<string, number>;
      }[];
      priority: number;
      cacheConfig?: {
        ttl: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.