Routing Rules

Configure intelligent routing rules for model selection and fallbacks.

List Routing Rules

Endpoint

GET /v1/management/routing-rules

Example

curl https://api.gateflow.ai/v1/management/routing-rules \
  -H "Authorization: Bearer gw_admin_..."

Response

{
  "rules": [
    {
      "id": "rule_abc123",
      "name": "cost-optimized-routing",
      "priority": 1,
      "enabled": true,
      "conditions": {
        "models": ["auto", "gpt-5.2"]
      },
      "actions": {
        "route_to": "gpt-5-mini",
        "fallbacks": ["claude-haiku-4-5-20251015"]
      },
      "created_at": "2026-02-01T10:00:00Z"
    },
    {
      "id": "rule_def456",
      "name": "premium-routing",
      "priority": 2,
      "enabled": true,
      "conditions": {
        "api_keys": ["key_premium_*"],
        "models": ["auto"]
      },
      "actions": {
        "route_to": "gpt-5.2",
        "fallbacks": ["claude-sonnet-4-5-20250929", "gemini-3-pro"]
      },
      "created_at": "2026-02-05T10:00:00Z"
    }
  ]
}

Create Routing Rule

Endpoint

POST /v1/management/routing-rules

Request Body

Parameter	Type	Required	Description
name	string	Yes	Rule name
priority	integer	No	Evaluation order (lower = first)
enabled	boolean	No	Whether rule is active
conditions	object	Yes	When to apply rule
actions	object	Yes	What to do

Condition Fields

Field	Type	Description
models	array	Match these model requests
api_keys	array	Match these API key patterns
headers	object	Match request headers
metadata	object	Match request metadata
time_range	object	Match time of day
token_estimate	object	Match estimated tokens

Action Fields

Field	Type	Description
route_to	string	Primary model to use
fallbacks	array	Fallback model chain
retry	object	Retry configuration
cache	object	Cache configuration
transform	object	Request transformation

Examples

Cost-Optimized Routing

curl -X POST https://api.gateflow.ai/v1/management/routing-rules \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cost-optimized",
    "priority": 1,
    "conditions": {
      "models": ["auto"],
      "metadata": {
        "prefer": "cost"
      }
    },
    "actions": {
      "route_to": "gpt-5-mini",
      "fallbacks": ["claude-haiku-4-5-20251015", "gemini-3-flash"]
    }
  }'

Quality-First Routing

curl -X POST https://api.gateflow.ai/v1/management/routing-rules \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quality-first",
    "priority": 2,
    "conditions": {
      "models": ["auto"],
      "metadata": {
        "prefer": "quality"
      }
    },
    "actions": {
      "route_to": "gpt-5.2",
      "fallbacks": ["claude-sonnet-4-5-20250929", "gemini-3-pro"]
    }
  }'

Time-Based Routing

curl -X POST https://api.gateflow.ai/v1/management/routing-rules \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "off-peak-routing",
    "priority": 3,
    "conditions": {
      "time_range": {
        "start": "22:00",
        "end": "06:00",
        "timezone": "America/New_York"
      }
    },
    "actions": {
      "route_to": "gpt-5-mini",
      "cache": {
        "enabled": true,
        "ttl_seconds": 3600
      }
    }
  }'

Large Request Routing

curl -X POST https://api.gateflow.ai/v1/management/routing-rules \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "large-context-routing",
    "priority": 4,
    "conditions": {
      "token_estimate": {
        "min": 50000
      }
    },
    "actions": {
      "route_to": "gemini-3-pro",
      "fallbacks": ["claude-sonnet-4-5-20250929"]
    }
  }'

Header-Based Routing

curl -X POST https://api.gateflow.ai/v1/management/routing-rules \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "enterprise-routing",
    "priority": 5,
    "conditions": {
      "headers": {
        "X-Customer-Tier": "enterprise"
      }
    },
    "actions": {
      "route_to": "gpt-5.2",
      "retry": {
        "max_attempts": 5,
        "initial_delay_ms": 500
      }
    }
  }'

Response

{
  "id": "rule_xyz789",
  "name": "cost-optimized",
  "priority": 1,
  "enabled": true,
  "conditions": {
    "models": ["auto"],
    "metadata": {
      "prefer": "cost"
    }
  },
  "actions": {
    "route_to": "gpt-5-mini",
    "fallbacks": ["claude-haiku-4-5-20251015", "gemini-3-flash"]
  },
  "created_at": "2026-02-16T10:00:00Z"
}

Get Routing Rule

Endpoint

GET /v1/management/routing-rules/{rule_id}

Example

curl https://api.gateflow.ai/v1/management/routing-rules/rule_abc123 \
  -H "Authorization: Bearer gw_admin_..."

Update Routing Rule

Endpoint

PATCH /v1/management/routing-rules/{rule_id}

Example

curl -X PATCH https://api.gateflow.ai/v1/management/routing-rules/rule_abc123 \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 2,
    "actions": {
      "fallbacks": ["claude-sonnet-4-5-20250929", "gemini-3-pro", "mistral-large-3"]
    }
  }'

Enable/Disable Rule

Endpoint

POST /v1/management/routing-rules/{rule_id}/enable
POST /v1/management/routing-rules/{rule_id}/disable

Example

curl -X POST https://api.gateflow.ai/v1/management/routing-rules/rule_abc123/disable \
  -H "Authorization: Bearer gw_admin_..."

Delete Routing Rule

Endpoint

DELETE /v1/management/routing-rules/{rule_id}

Example

curl -X DELETE https://api.gateflow.ai/v1/management/routing-rules/rule_abc123 \
  -H "Authorization: Bearer gw_admin_..."

Test Routing Rule

Test how a request would be routed.

Endpoint

POST /v1/management/routing-rules/test

Example

curl -X POST https://api.gateflow.ai/v1/management/routing-rules/test \
  -H "Authorization: Bearer gw_admin_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Hello"}],
    "metadata": {
      "prefer": "cost"
    }
  }'

Response

{
  "matched_rule": {
    "id": "rule_abc123",
    "name": "cost-optimized"
  },
  "resolved_model": "gpt-5-mini",
  "fallback_chain": ["claude-haiku-4-5-20251015", "gemini-3-flash"],
  "estimated_cost": 0.0001
}

Errors

Code	Description
400	Invalid rule configuration
401	Invalid admin key
404	Rule not found
409	Conflicting rule priority
422	Invalid model in route/fallbacks

See Also

• Intelligent Routing - Routing guide
• Model Fallbacks - Fallback configuration
• Cost vs Performance - Optimization guide