Skip to main content
POST
/
api
/
v1
/
routing-preferences
Create Routing Preference
curl --request POST \
  --url https://api.example.com/api/v1/routing-preferences \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "rules": [
    {}
  ],
  "examples": [
    {}
  ],
  "confidence_floor_overrides": {},
  "scope": "<string>",
  "is_default": true
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt

Use this file to discover all available pages before exploring further.

Create a new Routing Studio preference. Idempotent — the same Idempotency-Key header replays the same response. Creating a preference does not auto-bind it to a key. Use PUT /api/v1/keys//routing-preference to opt a key in, or edit rules directly on a key via PUT /api/v1/keys//routing-rules.

​
Authentication

Requires a Bearer token with the billing API key scope.

​
Body

​
name
string
required
Preference name. 1–128 chars. May not reference upstream provider names (Claude, OpenAI, Anthropic, Gemini, fal.ai, etc.).
​
description
string
Free-text description. Up to 512 chars.
​
rules
object[]
Up to 50 keyword/regex rules. Each rule has pattern (ECMAScript regex source, ≤512 chars), target_mode (a Theo mode), optional target_engine (Theo-branded engine id), confidence (clamped server-side to [0.5, 0.99]), and an optional description.
​
examples
object[]
Up to 30 few-shot examples injected into the classifier’s system prompt. Each example has prompt (≤1024 chars), expected_mode, and optional expected_engine.
​
confidence_floor_overrides
object
Per-mode replacements for the global 0.85 promotion floor. Values are clamped to [0.5, 0.99].
​
scope
string
"personal" (default) or "team". Team scope requires an active org and the manageWebhooks permission.
​
is_default
boolean
Mark this preference as the default for its scope. At most one default per scope.

​
Request Examples

curl -X POST https://www.hitheo.ai/api/v1/routing-preferences \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ContractIQ Legal",
    "description": "Contract terms get the analytical engine.",
    "rules": [
      {
        "pattern": "\\b(clause|provision|indemnity|warranty)\\b",
        "target_mode": "think",
        "confidence": 0.92,
        "description": "Contract terms get the analytical engine."
      }
    ],
    "examples": [
      { "prompt": "Look at this clause", "expected_mode": "think" }
    ]
  }'

​
Errors

  • 400 routing_preference_invalid — Vendor-named label or pattern, uncompilable regex, unknown engine, or rule/example cap exceeded.
  • 400 org_required — scope: "team" without an active organization.
  • 403 missing_scope — API key lacks the billing scope.
  • 409 conflict — is_default: true already set for this scope.