Routing | JoyToken | Documentation

JoyToken selects the model and provider for every request. Send model: "auto" and control the eligible routing range with tier and API key policy.

Common Requests

Goal	Request
Automatic routing	`model: "auto"`
Select a tier	`model: "auto"` + `tier: “economy"
Restrict eligible models	Set a model blacklist in API key policy

Tiers

Tier	Use
`economy`	Cost-first, batch, low-risk tasks
`standard`	Balanced default
`premium`	Quality-first or critical evaluation tasks

Wallet Fallback

When the request uses model: "auto" and the current tier lacks balance, JoyToken may try another tier allowed by policy.

Current tier	Fallback order
`premium`	`standard` -> `economy`
`standard`	`premium` -> `economy`
`economy`	`standard` -> `premium`

Concrete model IDs are not accepted in requests. If policy, balance, or budget filtering leaves no eligible candidate, the request returns an error.

Orchestration (Multi-task Planning)

For complex prompts, JoyToken may handle a single model: "auto" request in orchestration mode: it first builds a task plan, runs each task with a selected sub-model, then aggregates a final answer. You do not opt in explicitly; the gateway decides based on the request.

How to detect it

Signal	Meaning
`plan` (top level)	Ordered task list, present only in orchestration mode
`choices[].message.content`	A JSON-encoded array of per-task outputs (`content` + `title`) instead of a single string
`metadata` (array)	One entry per task, including reserved `__planner__` and `__final__` tasks
streaming planning event	A leading chunk whose `orchestration.phase` is `planning` carries the ordered `plan`, followed by the `__planner__` metadata event
streaming task chunk	Each task’s content chunk carries an `orchestration` field (`task_id`, `task_seq`, `task_status`, `title`)
streaming `metadata` event	One standalone metadata event per task (a single object, not an array), emitted right after that task’s content

Task lifecycle

Field	Meaning
`task_id`	Task identifier; `__planner__` and `__final__` are reserved
`task_seq`	Execution order; `0` is the planner
`task_status`	Task status, e.g. `DONE`
`tag`	Task role, e.g. `orchestration`, `search`, `reasoning`, `writing`, `aggregation`
`title`	Human-readable task title

In orchestration mode each task is billed separately (one metadata/billing entry per task) and may use a different sub-model. Parse choices[].message.content as JSON before rendering, and sum billing.credits_used across all task metadata entries.

Confirm Routing

Signal	Meaning
`metadata.model`	Final JoyToken model
`metadata.tier`	Billing and routing tier
`metadata.billing`	Credits and token usage

Troubleshooting

Symptom	Check first
tier not allowed	API key policy allows the tier
no eligible model	tier, blacklist, wallet, and key budget
IP not allowed	server egress IP is allowlisted
`auto` fails	policy, tier, and balance still leave candidate models
concrete model ID rejected	replace it with `auto`