Routing
The models the caller's organization sent requests to in the last 30 days, and the fallback each gets.
A request that sends a model's catalog ID moves to the model's next offering when one fails, with no policy. Each model lists its offerings in the order such a request tries them before automatic selection reorders it, each with its input price for this organization and who runs the built-in tools on it, beside its traffic: how many requests a backup served, and how many named one offering or a policy instead, by API key and provider. The traffic is the workspaces the caller may see in their active organization, by the rule the organization's usage reads use.
Enter your API key here (sent as Otari-Key header).
Only the offerings a request billed to this workspace may call.
Successful Response
The automatic fallbacks the caller's organization used.
How many days of traffic the counts cover.
Validation Error
GET /api/v1/organizations/me/automatic-fallbacks HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
"models": [
{
"fell_back": 1,
"id": "text",
"name": "text",
"offerings": [
{
"input_price": 1,
"otari_tools": [
"text"
],
"own_tools": [
"text"
],
"provider": "text",
"provider_type": "text",
"selector": "text"
}
],
"pinned": 1,
"pinned_keys": [
{
"api_key_id": "text",
"key_name": "text",
"provider": "text",
"requests": 1
}
],
"pinned_provider": "text",
"requests": 1
}
],
"window_days": 1
}List the routing policies in force in the workspaces this caller may see.
Stored policies from the caller's visible workspaces plus the config-file policies, which are deployment-wide and resolve in every workspace. The response is the shape GET /api/v1/routing/policies answers, narrowed to the caller's own organization, and narrowed again to one workspace when workspace_id names one.
Enter your API key here (sent as Otari-Key header).
Maximum entries to return, stored and config-file together.
1000Only stored entries in this workspace. Config-file entries are always included, being deployment-wide. Omit for every workspace this caller may see.
Successful Response
A routing policy and where it is defined.
falseValidation Error
GET /api/v1/organizations/me/routing-policies HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
{
"created_at": "text",
"is_dynamic": false,
"name": "text",
"source": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"updated_at": "text",
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}
]Create or update a stored policy in one of the organization's workspaces.
Organization owners and admins only. workspace_id is required and must name a workspace of the caller's own organization; user_id is not accepted here.
Enter your API key here (sent as Otari-Key header).
Request to create or update a routing policy.
Model name callers send, e.g. 'fast'.
Current name of the policy to rename, in the same scope, meaning the same workspace and the same user. A rename never moves a policy between them. The stored row keeps its id and created_at and takes name and spec. Sending it asserts that policy exists, so a name with no stored row is a 404 rather than a create, even when it equals name. Omit to create or update the policy named name. Renaming changes what callers must send as model; usage already recorded keeps the old name.
User this policy belongs to. Omit for a policy every caller in the workspace sees. A user-scoped policy resolves only for that user and shadows the workspace-wide one of the same name.
Workspace this policy belongs to. Omit for the deployment's default workspace. The policy resolves only for requests in that workspace, so two workspaces can each define their own 'fast'.
Successful Response
A routing policy and where it is defined.
falseValidation Error
POST /api/v1/organizations/me/routing-policies HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 153
{
"name": "text",
"rename_from": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"created_at": "text",
"is_dynamic": false,
"name": "text",
"source": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"updated_at": "text",
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}Delete a stored policy from one of the organization's workspaces. Owners and admins only.
Enter your API key here (sent as Otari-Key header).
Delete the policy in this workspace of the caller's organization.
Successful Response
No content
Validation Error
DELETE /api/v1/organizations/me/routing-policies/{name} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
No content
List every routing policy in force in your organization, from config.yml and from storage.
Every scope at once, workspace-wide and user-scoped alike: this is the master-key management view, not what any one caller resolves.
Enter your API key here (sent as Otari-Key header).
Only stored policies in this workspace. Config-file policies are always included, being deployment-wide. Omit to list the stored policies of every workspace in your organization.
Successful Response
A routing policy and where it is defined.
falseValidation Error
GET /api/v1/routing/policies HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
{
"created_at": "text",
"is_dynamic": false,
"name": "text",
"source": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"updated_at": "text",
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}
]Create or update a stored policy in one workspace, optionally for one user.
Omitting workspace_id means the deployment's default workspace, which is where an operator acting deployment-wide writes.
Enter your API key here (sent as Otari-Key header).
Request to create or update a routing policy.
Model name callers send, e.g. 'fast'.
Current name of the policy to rename, in the same scope, meaning the same workspace and the same user. A rename never moves a policy between them. The stored row keeps its id and created_at and takes name and spec. Sending it asserts that policy exists, so a name with no stored row is a 404 rather than a create, even when it equals name. Omit to create or update the policy named name. Renaming changes what callers must send as model; usage already recorded keeps the old name.
User this policy belongs to. Omit for a policy every caller in the workspace sees. A user-scoped policy resolves only for that user and shadows the workspace-wide one of the same name.
Workspace this policy belongs to. Omit for the deployment's default workspace. The policy resolves only for requests in that workspace, so two workspaces can each define their own 'fast'.
Successful Response
A routing policy and where it is defined.
falseValidation Error
POST /api/v1/routing/policies HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 153
{
"name": "text",
"rename_from": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"created_at": "text",
"is_dynamic": false,
"name": "text",
"source": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"updated_at": "text",
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}Compile a policy and return the plan, without dispatching anything.
Operator-gated, and deliberately so: the response enumerates the policy's targets, which is exactly the information a policy exists to keep off the wire. It is a management surface, not a caller-facing one.
Accepts an unsaved spec as well as a saved name, so a form can validate what the operator is about to save. The response includes dropped candidates with reasons, which is the part that catches a "failover" policy that has quietly compiled down to a single attempt.
Enter your API key here (sent as Otari-Key header).
Ask what a policy would do, without dispatching anything.
Either name a stored/configured policy (name) or pass a draft spec that
has not been saved. The draft form is what makes authoring-time validation
possible: the compiler filters candidates, so a chain can compile down to one
attempt, and an author needs to see that before saving rather than during an
outage.
Simulate an API key's allow-list. Omit for unrestricted.
Simulated budget remaining, USD.
Simulated budget usage percentage.
Evaluate conditions as this API key id.
An existing policy to explain.
Evaluate conditions as this user.
Resolve name and the policy's candidate selectors in this workspace. Omit for the deployment's default workspace.
Successful Response
The plan a policy compiles to for the given inputs.
Validation Error
POST /api/v1/routing/policies/explain HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 219
{
"allowed_models": [
"text"
],
"budget_remaining_usd": 1,
"budget_used_pct": 1,
"key_id": "text",
"name": "text",
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"candidates": [
{
"dispatch_model": "text",
"instance": "text",
"model": "text",
"position": 1,
"selection_reason": "text"
}
],
"dropped": [
{
"detail": "text",
"reason": "text",
"selector": "text"
}
],
"guardrails": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"is_dynamic": true,
"name": "text",
"router_backend": "text",
"router_candidates": [
"text"
],
"router_weights": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"selection_reason": "text"
}Delete a stored policy in one scope.
Enter your API key here (sent as Otari-Key header).
Delete the policy scoped to this user. Omit to delete the workspace-wide one.
Delete the policy in this workspace. Omit for the deployment's default workspace.
Successful Response
No content
Validation Error
DELETE /api/v1/routing/policies/{name} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
No content
Recommend the model a subagent about to start should run on.
The harness sends the facts it holds at spawn time: its own ids for the session and the spawning tool call, the subagent type, the task, the parent's model and the model the caller asked for, if any. The recommender this build binds picks one of the candidate models and the answer names it. By default the deployment asks the subagent router an operator switched on in the dashboard to choose among agent_recommender_candidates for Claude Code and among the request's own candidates for pi; a bootstrap may bind a recommender of its own, which the caller never configures. Where the recommender reports them, the answer also carries a one-line reason and its probability for each candidate.
Authentication modes:
Master key: the
userfield is required and names who the decision is billed to.API key: the decision is billed to the key's own user.
Enter your API key here (sent as Otari-Key header).
A coding agent about to start a subagent, asking which model it should run on.
Every field but user is a fact the harness already holds at spawn time.
The prompt is the task the subagent is given; it is read for the
recommendation and never stored or logged.
The subagent type: a built-in such as Explore or Plan, or a custom agent's name.
The models the subagent may be sent to, as Otari model ids (<provider>:<model>), each with what it is for (or null when the name says enough). Required for pi, refused for claude-code.
The caller's short description of the task.
""The agent harness asking. It decides the candidates: agent_recommender_candidates, Claude Code's own aliases, for claude-code, and the request's own candidates for pi.
The model the parent conversation runs on, as the harness names it.
The task the subagent is given.
The model the caller asked for, if any. Sent as a fact; the recommendation is the gateway's.
The harness's own id for the session the spawn happens in.
The harness's own id for the tool call that spawns the subagent.
User ID the decision is billed to when asking with the master key; not sent upstream.
Successful Response
The model recommended for the subagent.
A model alias or id the harness can start the subagent on.
Why, in one short sentence the harness may show.
No subagent router is switched on, or a master-key call names no user.
Validation Error
POST /api/v1/routing/recommend HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 299
{
"agent_type": "Explore",
"description": "Find the budget reservation code",
"harness": "claude-code",
"parent_model": "claude-opus-5",
"prompt": "Find where budgets are reserved before dispatch and report the call chain.",
"session_id": "bf05abe2-5ff2-4eb0-8459-ab578d5c9468",
"tool_use_id": "toolu_01Ab3dEfGh"
}{
"model": "sonnet",
"probabilities": {
"haiku": 0.21,
"opus": 0.07,
"sonnet": 0.72
},
"reason": "sonnet with 72%"
}Last updated
Was this helpful?
