Orq.ai Routing Rules API

openapi: 3.2.0
info:
  title: orq.ai Routing Rules API
  version: '2.0'
  description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Routing Rules
  description: Routing Rules conditionally select models and enforce request plugins for AI Gateway traffic. Rules are evaluated by ascending priority and may be scoped to a project or the whole workspace.
paths:
  /v2/routing-rules:
    get:
      tags:
      - Routing Rules
      summary: List routing rules
      description: Returns routing rules ordered by ascending priority. Supports cursor pagination, search, status, project, and referenced-model filters.
      operationId: RoutingRuleList
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
      - name: starting_after
        in: query
        schema:
          type: string
      - name: ending_before
        in: query
        schema:
          type: string
      - name: project_id
        in: query
        schema:
          type: string
      - name: search
        in: query
        schema:
          type: string
      - name: enabled
        in: query
        schema:
          type: boolean
      - name: model
        in: query
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRoutingRulesResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: routingRules
      x-speakeasy-name-override: list
      x-cli-hidden: true
      x-cli-group: routingRules
      x-cli-name: list
      x-code-samples:
      - lang: curl
        label: Core - List routing rules
        source: "curl --get 'https://my.orq.ai/v2/routing-rules' \\\n  --header \"Authorization: Bearer $ORQ_API_KEY\" \\\n  --data-urlencode 'limit=25'\n"
      - lang: python
        label: Python - List routing rules
        source: "import os\nfrom orq_ai_sdk import Orq\n\nclient = Orq(api_key=os.environ[\"ORQ_API_KEY\"])\npage = client.routing_rules.list(limit=25)\n\nfor rule in page.data:\n    print(rule._id, rule.display_name)\n"
      - lang: typescript
        label: Node.js - List routing rules
        source: "import { Orq } from '@orq-ai/node';\n\nconst client = new Orq({ apiKey: process.env.ORQ_API_KEY });\nconst page = await client.routingRules.list({ limit: 25 });\n\nfor (const rule of page.data) {\n  console.log(rule._id, rule.displayName);\n}\n"
    post:
      tags:
      - Routing Rules
      summary: Create a routing rule
      description: Creates a routing rule with metadata and optional model, plugin, priority, and matching configuration. Rules default to disabled when `enabled` is omitted.
      operationId: RoutingRuleCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoutingRuleRequest'
        required: true
      responses:
        '201':
          description: Routing rule created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingRule'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: routingRules
      x-speakeasy-name-override: create
      x-cli-hidden: true
      x-cli-group: routingRules
      x-cli-name: create
      x-code-samples:
      - lang: curl
        label: Core - Create routing rule
        source: "curl --request POST \\\n  --url 'https://my.orq.ai/v2/routing-rules' \\\n  --header \"Authorization: Bearer $ORQ_API_KEY\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"display_name\": \"Private customer traffic\",\n    \"description\": \"Routes private customer requests through the guarded model path.\"\n  }'\n"
      - lang: python
        label: Python - Create routing rule
        source: "import os\nfrom orq_ai_sdk import Orq\n\nclient = Orq(api_key=os.environ[\"ORQ_API_KEY\"])\n\nrule = client.routing_rules.create(\n    display_name=\"Private customer traffic\",\n    description=\"Routes private customer requests through the guarded model path.\",\n)\n\nprint(rule._id)\n"
      - lang: typescript
        label: Node.js - Create routing rule
        source: "import { Orq } from '@orq-ai/node';\n\nconst client = new Orq({ apiKey: process.env.ORQ_API_KEY });\nconst rule = await client.routingRules.create({\n  displayName: 'Private customer traffic',\n  description:\n    'Routes private customer requests through the guarded model path.',\n});\n\nconsole.log(rule._id);\n"
  /v2/routing-rules/used-models:
    get:
      tags:
      - Routing Rules
      summary: List models used by routing rules
      description: Returns the distinct model references used by routing rules in the requested scope.
      operationId: RoutingRuleListUsedModels
      parameters:
      - name: project_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListRoutingRuleUsedModelsResponse'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: routingRules
      x-speakeasy-name-override: listUsedModels
      x-cli-hidden: true
      x-cli-group: routingRules
      x-cli-name: listUsedModels
      x-code-samples:
      - lang: curl
        label: Core - List models used by routing rules
        source: "curl --get 'https://my.orq.ai/v2/routing-rules/used-models' \\\n  --header \"Authorization: Bearer $ORQ_API_KEY\"\n"
      - lang: python
        label: Python - List routing rule models
        source: 'import os

          from orq_ai_sdk import Orq


          client = Orq(api_key=os.environ["ORQ_API_KEY"])

          result = client.routing_rules.list_used_models()


          print(result.models)

          '
      - lang: typescript
        label: Node.js - List routing rule models
        source: 'import { Orq } from ''@orq-ai/node'';


          const client = new Orq({ apiKey: process.env.ORQ_API_KEY });

          const result = await client.routingRules.listUsedModels();


          console.log(result.models);

          '
  /v2/routing-rules/{routing_rule_id}:
    get:
      tags:
      - Routing Rules
      summary: Retrieve a routing rule
      description: Retrieves a routing rule by its unique identifier.
      operationId: RoutingRuleGet
      parameters:
      - name: routing_rule_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingRule'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Not permitted for this key, project or workspace. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: routingRules
      x-speakeasy-name-override: retrieve
      x-cli-hidden: true
      x-cli-group: routingRules
      x-cli-name: retrieve
      x-code-samples:
      - lang: curl
        label: Core - Retrieve routing rule
        source: "curl --request GET \\\n  --url 'https://my.orq.ai/v2/routing-rules/rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V' \\\n  --header \"Authorization: Bearer $ORQ_API_KEY\"\n"
      - lang: python
        label: Python - Retrieve routing rule
        source: "import os\nfrom orq_ai_sdk import Orq\n\nclient = Orq(api_key=os.environ[\"ORQ_API_KEY\"])\nrule = client.routing_rules.retrieve(\n    routing_rule_id=\"rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V\",\n)\n\nprint(rule.display_name)\n"
      - lang: typescript
        label: Node.js - Retrieve routing rule
        source: "import { Orq } from '@orq-ai/node';\n\nconst client = new Orq({ apiKey: process.env.ORQ_API_KEY });\nconst rule = await client.routingRules.retrieve({\n  routingRuleId: 'rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V',\n});\n\nconsole.log(rule.displayName);\n"
    delete:
      tags:
      - Routing Rules
      summary: Delete a routing rule
      description: Permanently deletes a routing rule.
      operationId: RoutingRuleDelete
      parameters:
      - name: routing_rule_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Routing rule deleted successfully
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: routingRules
      x-speakeasy-name-override: delete
      x-cli-hidden: true
      x-cli-group: routingRules
      x-cli-name: delete
      x-code-samples:
      - lang: curl
        label: Core - Delete routing rule
        source: "curl --request DELETE \\\n  --url 'https://my.orq.ai/v2/routing-rules/rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V' \\\n  --header \"Authorization: Bearer $ORQ_API_KEY\"\n"
      - lang: python
        label: Python - Delete routing rule
        source: "import os\nfrom orq_ai_sdk import Orq\n\nclient = Orq(api_key=os.environ[\"ORQ_API_KEY\"])\nclient.routing_rules.delete(\n    routing_rule_id=\"rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V\",\n)\n"
      - lang: typescript
        label: Node.js - Delete routing rule
        source: "import { Orq } from '@orq-ai/node';\n\nconst client = new Orq({ apiKey: process.env.ORQ_API_KEY });\nawait client.routingRules.delete({\n  routingRuleId: 'rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V',\n});\n"
    patch:
      tags:
      - Routing Rules
      summary: Update a routing rule
      description: Partially updates routing-rule metadata or configuration. Project scope is immutable.
      operationId: RoutingRuleUpdate
      parameters:
      - name: routing_rule_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRoutingRuleRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingRule'
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-speakeasy-group: routingRules
      x-speakeasy-name-override: update
      x-cli-hidden: true
      x-cli-group: routingRules
      x-cli-name: update
      x-code-samples:
      - lang: curl
        label: Core - Configure routing rule
        source: "curl --request PATCH \\\n  --url 'https://my.orq.ai/v2/routing-rules/rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V' \\\n  --header \"Authorization: Bearer $ORQ_API_KEY\" \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"enabled\": true,\n    \"priority\": 10,\n    \"models_config\": {\n      \"mode\": \"fallback\",\n      \"models\": [{\"model\": \"openai/gpt-5\"}],\n      \"fallback_on_codes\": [429, 503]\n    }\n  }'\n"
      - lang: python
        label: Python - Configure routing rule
        source: "import os\nfrom orq_ai_sdk import Orq\n\nclient = Orq(api_key=os.environ[\"ORQ_API_KEY\"])\nrule = client.routing_rules.update(\n    routing_rule_id=\"rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V\",\n    enabled=True,\n    priority=10,\n    models_config={\n        \"mode\": \"fallback\",\n        \"models\": [{\"model\": \"openai/gpt-5\"}],\n        \"fallback_on_codes\": [429, 503],\n    },\n)\n\nprint(rule.updated_at)\n"
      - lang: typescript
        label: Node.js - Configure routing rule
        source: "import { Orq } from '@orq-ai/node';\n\nconst client = new Orq({ apiKey: process.env.ORQ_API_KEY });\nconst rule = await client.routingRules.update({\n  routingRuleId: 'rrl_01HZXW2K7Y8Q9M0N1P2R3S4T5V',\n  enabled: true,\n  priority: 10,\n  modelsConfig: {\n    mode: 'fallback',\n    models: [{ model: 'openai/gpt-5' }],\n    fallbackOnCodes: [429, 503],\n  },\n});\n\nconsole.log(rule.updatedAt);\n"
components:
  schemas:
    RoutingRuleCacheConfig:
      required:
      - ttl
      type: object
      properties:
        ttl:
          type: integer
          description: Cache time to live in seconds. Maximum 259200 seconds (3 days).
          format: int32
    RoutingRuleModel:
      type: object
      properties:
        model:
          type: string
        display_name:
          type: string
        weight:
          type: number
          format: double
        integration_id:
          type: string
    RoutingRule:
      required:
      - _id
      - created_at
      - updated_at
      - created_by_id
      - updated_by_id
      - project_id
      - display_name
      - description
      - enabled
      - plugins
      - priority
      type: object
      properties:
        _id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by_id:
          type: string
        updated_by_id:
          type: string
        project_id:
          type: string
          description: Project that contains the rule. Empty for workspace-wide rules.
        display_name:
          type: string
          description: Human-readable routing-rule name.
        description:
          type: string
        enabled:
          type: boolean
        expression:
          $ref: '#/components/schemas/RoutingRuleExpression'
        models_config:
          $ref: '#/components/schemas/RoutingRuleModelsConfig'
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/RoutingRulePlugin'
        priority:
          type: integer
          description: Evaluation order. Lower values are evaluated first.
          format: int32
        cache_config:
          $ref: '#/components/schemas/RoutingRuleCacheConfig'
    UpdateRoutingRuleRequest:
      required: []
      type: object
      properties:
        display_name:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        expression:
          $ref: '#/components/schemas/RoutingRuleExpression'
        models_config:
          $ref: '#/components/schemas/RoutingRuleModelsConfig'
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/RoutingRulePlugin'
        priority:
          type: integer
          format: int32
        cache_config:
          $ref: '#/components/schemas/RoutingRuleCacheConfig'
    RoutingRuleExpression:
      type: object
      properties:
        config:
          type: object
        cel:
          type: string
          description: CEL expression used to match requests. Empty means the rule always matches.
    RoutingRulePlugin:
      type: object
      properties:
        id:
          type: string
          description: Plugin discriminator.
        language:
          type: string
          description: "Languages, regions and entity types are checked against the live\n pii-detection capabilities catalog when the rule is saved, not pinned\n here, so a language or region the detector gains becomes writable without\n a future update."
        entities:
          type: array
          items:
            type: string
          description: Entity types to redact. On their own a strict allowlist; alongside regions they add to the region coverage.
        on_failure:
          type: string
        threshold:
          type: number
          format: double
        mask:
          type: array
          items:
            type: string
        regions:
          type: array
          items:
            type: string
          description: 'Regions of coverage by ISO 3166-1 alpha-2 code, or ["all"]. Combines with entities: the two selections are unioned.'
        entity_thresholds:
          type: object
          additionalProperties:
            type: number
            format: double
          description: Per-entity-type confidence cutoff. Every key must also appear in entities.
    ListRoutingRulesResponse:
      required:
      - object
      - data
      - has_more
      type: object
      properties:
        object:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/RoutingRule'
        has_more:
          type: boolean
    RoutingRuleModelsConfig:
      type: object
      properties:
        mode:
          type: string
          description: Load-balancing mode.
        models:
          type: array
          items:
            $ref: '#/components/schemas/RoutingRuleModel'
        fallback_on_codes:
          maxItems: 20
          uniqueItems: true
          type: array
          items:
            type: integer
            format: int32
            maximum: 599
            minimum: 400
          description: 'HTTP error status codes that trigger fallback. Only allowed in fallback mode. Empty uses the default: 408, 429, 500, 502, 503, 504, 529.'
    ListRoutingRuleUsedModelsResponse:
      required:
      - object
      - models
      type: object
      properties:
        object:
          type: string
        models:
          type: array
          items:
            type: string
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: integer
          description: gRPC status code, when the service reports one.
        details:
          type: array
          items: {}
          description: Additional error details, when the service reports any.
      required:
      - message
    CreateRoutingRuleRequest:
      required:
      - display_name
      type: object
      properties:
        display_name:
          type: string
        description:
          type: string
        project_id:
          type: string
          description: Optional project scope. Omit for a workspace-wide rule.
        enabled:
          type: boolean
          description: Whether the rule is active. Defaults to false when omitted.
        expression:
          $ref: '#/components/schemas/RoutingRuleExpression'
        models_config:
          $ref: '#/components/schemas/RoutingRuleModelsConfig'
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/RoutingRulePlugin'
        priority:
          type: integer
          format: int32
        cache_config:
          $ref: '#/components/schemas/RoutingRuleCacheConfig'
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
x-speakeasy-timeout: 600000