The routing document

The routing of a scope is one document. A scope is the project, one app (the x-proxium-source of its calls) or one key. Each saved change is a new version, and the highest version is in force.

The format

template: {id: acme, version: 2, tiers: [standard]}
routing:
  chat:
    standard:
      - "t:my-project.acme/fast-model"
      - {model: "t:my-project.acme/large-model", reasoning: low}
    code:
      - "t:my-project.acme/code-model"

Field	What it holds
routing	The request type, then the tier, then its chain. The first hop answers, and each next hop takes over on a failure.
A hop	provider/model, split at the first /. Or a map with model, reasoning, priority and weight.
reasoning	The reasoning level that the call sends: none, minimal, low, medium or high.
priority and weight	Hops next to each other with the same priority share the calls by weight. A hop with no priority has its place in the chain.
template	The routing template of the project, and the tiers that it wrote. Change it with proxium_use_routing_preset.
classify	The classification document of the scope. See classification.

A document holds only what its scope sets. A tier with no chain uses the next level: the app, then the key, then the project, then the gateway default.

The steps

1. Read the document and its version: proxium_read_routing_document, or GET /api/teams/{project}/routing/document.
2. Change it, as YAML or JSON.
3. Plan the change: proxium_plan_routing_document, or POST /api/teams/{project}/routing/document/plan. The answer names each fault with its path, each chain that moves, and each section that is added, changed or removed (sections, for example classify: removed). It saves nothing.
4. Apply it with the version of step 1: proxium_apply_routing_document, or PUT /api/teams/{project}/routing/document.

The apply is refused when another version is in force. Read the document again, and apply your change to that version. A fault names its path, for example routing.chat.code[1].reasoning: 'max' is not one of none, minimal, low, medium, high.

For an app or a key, send app or key to the MCP tool. The API takes scope_kind and scope_name in the query, or scope in the body.

Change one tier

To change one tier, or to insert or remove one hop, send steps and not a whole document: proxium_change_routing, or POST /api/teams/{project}/routing/document/change. The server applies the steps to the version in force and keeps every other section of the document, the classify section included.

{"version": 8, "steps": [
  {"op": "insert_hop", "tier": "code", "hop": "commandcode/reflection/beam:free", "position": 2},
  {"op": "remove_hop", "tier": "code", "hop": "ollama-cloud/beam"},
  {"op": "set_chain", "tier": "trivial", "chain": ["commandcode/stealth/glyph-cluster:free"]}
]}

Step	What it does
set_chain	Replaces the whole chain of a tier. An empty chain removes the tier.
insert_hop	Puts a hop at position (from 1) in the chain of a tier that exists. A position past the end appends.
remove_hop	Removes a hop, named as provider/model or by its position.

modality defaults to chat. The checks are those of the plan, and each fault names its step, such as steps[1]: the tier 'heavy' has no chat chain. With a fault the document stays as it was. With dry_run the answer is the plan and nothing is saved. The change is refused when another version is in force.

From the command line

proxium routing uses the login of proxium login. The project is --project, else the project of proxium login. For an app or a key, add --app NAME or --key PREFIX.

proxium routing export -o routing.yaml
proxium routing plan routing.yaml
proxium routing apply routing.yaml
proxium routing where --app support

The first line of an exported file names the project, the scope and the version:

# proxium routing: project=my-project version=3

plan and apply read that line. So a file goes back to the scope it came from, and an apply made from an old version is refused. apply shows the plan, and it applies nothing when the plan has a fault. The comments of an applied file stay: the next export gives them back.

To change one tier, name it:

proxium routing change --tier code --insert commandcode/reflection/beam:free --at 2
proxium routing change --tier trivial --set commandcode/stealth/glyph-cluster:free,ollama-cloud/glm-5.3-flash
proxium routing change --tier code --remove ollama-cloud/beam --dry-run

proxium routing versions lists the versions, and proxium routing rollback VERSION applies an earlier one again.

The versions

• proxium_list_routing_document_versions lists each version, who saved it and when.
• proxium_rollback_routing_document applies an earlier version again, as the next version. The template stays as it is.

Where a call goes

proxium_read_resolved_routing, or GET /api/teams/{project}/routing/resolved?app=…&key=…, answers for each tier the chain in force, the reasoning level of each hop, and the scope that set it.