Route Call

curl --request POST \
  --url https://api.example.com/route \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "task_hint": "default",
  "max_cost_usd": 0.05,
  "prefer_premium": false,
  "tier_preset": "balanced"
}
'

{}

API Reference

Route Call

S4-ROUTE-02 / S5-API-03 — paid LLM router (default tier).

Pricing tradeoff: x402 settles before we know the upstream-billed truth (usage.cost). A true post-call markup (usage_cost_usd * 1.10) would require x402 to support a settle-after-work refund hook; v2 doesn’t. Sprint 5 ships tiered flat charges instead — three paths, three prices, client picks the path matching its task_hint:

POST /route → $0.01 (extraction / summary / default) POST /route/premium →$ 0.05 (reasoning / code) POST /route/upgrade → $0.20 (prefer_premium=True)

Heavy callers subsidize light ones less than the Sprint 4 single-flat model, but the implementation stays predictable and auditable.

Auth: payment is enforced by the x402 middleware; this handler runs only after settle. No per-user identity is required — route is session-less by design.

POST

route

Route Call

curl --request POST \
  --url https://api.example.com/route \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "task_hint": "default",
  "max_cost_usd": 0.05,
  "prefer_premium": false,
  "tier_preset": "balanced"
}
'

{}

Body

application/json

S4-ROUTE-02 — request shape for POST /route.

prompt

string

required

Required string length: 1 - 20000

task_hint

string

default:default

max_cost_usd

number

default:0.05

Required range: x >= 0

prefer_premium

boolean

default:false

tier_preset

string

default:balanced

Pattern: ^(quality|balanced|budget|free)$

Response

Successful Response

The response is of type Response Route Call Route Post · object.

Trade Research Pro Route Call Premium

⌘I