Smart Routing API

Overview

Smart Routing automatically selects a model from a configured model pool according to request complexity. In the System API, a route is represented by an API-key record with smart_routing: true; it uses the same /api/token/ create, update, status, reveal, and delete endpoints as a standard key.

Console label	API field	Purpose
Simple	`simple`	Fast and cost-efficient requests
Complex	`complex`	More demanding tasks
Ultra	`super`	Highest-capability baseline tier

The stored tier object also contains reasoning. The current console sets it to the same model as simple for compatibility.

smart_route_tiers is a JSON-encoded string. Do not send it as a nested JSON object.

Read the current presets

Preset model IDs are deployment configuration. Retrieve them from /api/status instead of copying model names from screenshots:

status_response=$(curl -fsS "$BASE_URL/api/status")

jq -e '
  .success == true
  and .data.smart_routing_enabled == true
  and (.data.smart_routing_model_aliases | index("auto") != null)
' <<< "$status_response" >/dev/null

presets=$(jq -er '.data.smart_routing_presets | fromjson' \
  <<< "$status_response")

jq '.' <<< "$presets"

The first check stops the workflow when Smart Routing is disabled or auto is not advertised as a routing alias. Select a preset and normalize the compatibility field:

tiers=$(jq -ce '
  .[0].pools
  | .reasoning = .simple
  | {simple, reasoning, complex, super}
  | select(all(.[]; type == "string" and length > 0))
' <<< "$presets")

Verify that all three active tiers contain model IDs available to the selected group. Compare them case-insensitively against .data.smart_routing_excluded_models; excluded models cannot be selected.

Create a Smart Routing key

name="smart-route-$(date +%s)-$RANDOM"

payload=$(jq -n \
  --arg name "$name" \
  --arg tiers "$tiers" '{
    name: $name,
    expired_time: -1,
    remain_quota: 0,
    unlimited_quota: true,
    model_limits_enabled: false,
    model_limits: "",
    allow_ips: "",
    group: "default",
    cross_group_retry: false,
    smart_routing: true,
    smart_route_tiers: $tiers
  }')

curl -fsS -X POST "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$payload" | jq

Creation does not return an ID. Locate the route with exclude_smart_routing=false:

route=$(curl -fsS --get "$BASE_URL/api/token/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "keyword=$name" \
  --data-urlencode "exclude_smart_routing=false" \
  --data-urlencode "p=1" \
  --data-urlencode "size=10")

route_id=$(jq -er --arg name "$name" '
  [.data.items[]
    | select(.name == $name and .smart_routing == true)]
  | if length == 1 then .[0].id
    else error("expected exactly one matching Smart Routing key")
    end
' <<< "$route")

Update the model pool

Read the current record and modify the decoded tier configuration. The update body must preserve every other mutable field.

current=$(curl -fsS "$BASE_URL/api/token/$route_id" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID")

new_tiers=$(jq -cer '
  .data.smart_route_tiers
  | fromjson
  | .complex = "YOUR_COMPLEX_MODEL"
  | .reasoning = .simple
' <<< "$current")

update_payload=$(jq --arg tiers "$new_tiers" '.data | {
  id,
  name,
  expired_time,
  remain_quota,
  unlimited_quota,
  model_limits_enabled,
  model_limits,
  allow_ips,
  group,
  cross_group_retry,
  smart_routing,
  smart_route_tiers
} | .smart_routing = true | .smart_route_tiers = $tiers' <<< "$current")

curl -fsS -X PUT "$BASE_URL/api/token/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "$update_payload" | jq

Changes apply to subsequent requests made with the route key.

Reveal and use the route key

stored_key=$(curl -fsS -X POST "$BASE_URL/api/token/$route_id/key" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  | jq -er '.data.key')

route_api_key="sk-${stored_key#sk-}"

Use the inference endpoint and set model to auto:

curl -fsS https://api.mixroute.ai/v1/chat/completions \
  -H "Authorization: Bearer $route_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role":"user","content":"Summarize the tradeoffs of this architecture."}
    ]
  }' | jq

Do not send the system access token to the inference endpoint.

Routing statistics

Read aggregate statistics for all route keys:

curl -fsS "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" | jq

Filter by key and Unix-second time range:

curl -fsS --get "$BASE_URL/api/token/smart_route/stats" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "New-Api-User: $USER_ID" \
  --data-urlencode "token_id=$route_id" \
  --data-urlencode "start=START_UNIX_SECONDS" \
  --data-urlencode "end=END_UNIX_SECONDS" | jq

The response includes requests, actual_quota, saved_quota, daily entries with baseline and actual, tier_dist, and trial_start_ts. Read current service-fee and trial configuration from /api/status:

curl -fsS "$BASE_URL/api/status" | jq '{
  trial_days: .data.smart_routing_free_trial_days,
  service_fee_percent: .data.smart_routing_service_fee_percent
}'

Operational constraints

Requests use the OpenAI-compatible /v1/chat/completions format.
Claude targets are accessed through OpenAI compatibility mode, so Claude-native-only features may not be available.
Switching target models can prevent provider-side prompt-cache reuse.
Disable a route through the status-only update endpoint before deleting it when rotating production credentials.

For the console workflow and integration links, see Smart Routing.

Popular Models

OpenAI SDK Usage

System API

Text Series

Embedding Series

Image Series

Video Series

Others

Overview

Read the current presets

Create a Smart Routing key

Update the model pool

Reveal and use the route key

Routing statistics

Operational constraints

​Overview

​Read the current presets

​Create a Smart Routing key

​Update the model pool

​Reveal and use the route key

​Routing statistics

​Operational constraints

Overview

Read the current presets

Create a Smart Routing key

Update the model pool

Reveal and use the route key

Routing statistics

Operational constraints