For the complete documentation index, see llms.txt. This page is also available as Markdown.

Routing

List Automatic Fallbacks

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
workspace_idstring · uuid · nullableOptional

Only the offerings a request billed to this workspace may call.

Responses
200

Successful Response

application/json

The automatic fallbacks the caller's organization used.

window_daysintegerRequired

How many days of traffic the counts cover.

get/api/v1/organizations/me/automatic-fallbacks
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 Visible Routing Policies

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
limitinteger · min: 1 · max: 1000Optional

Maximum entries to return, stored and config-file together.

Default: 1000
workspace_idstring · uuid · nullableOptional

Only stored entries in this workspace. Config-file entries are always included, being deployment-wide. Omit for every workspace this caller may see.

Responses
200

Successful Response

application/json

A routing policy and where it is defined.

created_atstring · nullableOptional
is_dynamicbooleanOptionalDefault: false
namestringRequired
sourcestringRequired
updated_atstring · nullableOptional
user_idstring · nullableOptional
workspace_idstring · uuid · nullableOptional
get/api/v1/organizations/me/routing-policies
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"
  }
]

Set Organization Routing Policy

post

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

Request to create or update a routing policy.

namestringRequired

Model name callers send, e.g. 'fast'.

rename_fromstring · nullableOptional

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_idstring · nullableOptional

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_idstring · uuid · nullableOptional

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'.

Responses
200

Successful Response

application/json

A routing policy and where it is defined.

created_atstring · nullableOptional
is_dynamicbooleanOptionalDefault: false
namestringRequired
sourcestringRequired
updated_atstring · nullableOptional
user_idstring · nullableOptional
workspace_idstring · uuid · nullableOptional
post/api/v1/organizations/me/routing-policies
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 Organization Routing Policy

delete

Delete a stored policy from one of the organization's workspaces. Owners and admins only.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
namestringRequired
Query parameters
workspace_idstring · uuid · nullableOptional

Delete the policy in this workspace of the caller's organization.

Responses
204

Successful Response

No content

delete/api/v1/organizations/me/routing-policies/{name}
DELETE /api/v1/organizations/me/routing-policies/{name} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*

No content

List Policies

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
workspace_idstring · uuid · nullableOptional

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.

Responses
200

Successful Response

application/json

A routing policy and where it is defined.

created_atstring · nullableOptional
is_dynamicbooleanOptionalDefault: false
namestringRequired
sourcestringRequired
updated_atstring · nullableOptional
user_idstring · nullableOptional
workspace_idstring · uuid · nullableOptional
get/api/v1/routing/policies
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"
  }
]

Set Policy

post

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

Request to create or update a routing policy.

namestringRequired

Model name callers send, e.g. 'fast'.

rename_fromstring · nullableOptional

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_idstring · nullableOptional

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_idstring · uuid · nullableOptional

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'.

Responses
200

Successful Response

application/json

A routing policy and where it is defined.

created_atstring · nullableOptional
is_dynamicbooleanOptionalDefault: false
namestringRequired
sourcestringRequired
updated_atstring · nullableOptional
user_idstring · nullableOptional
workspace_idstring · uuid · nullableOptional
post/api/v1/routing/policies
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"
}

Explain Policy

post

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

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.

allowed_modelsstring[] · nullableOptional

Simulate an API key's allow-list. Omit for unrestricted.

budget_remaining_usdnumber · nullableOptional

Simulated budget remaining, USD.

budget_used_pctnumber · nullableOptional

Simulated budget usage percentage.

key_idstring · nullableOptional

Evaluate conditions as this API key id.

namestring · nullableOptional

An existing policy to explain.

user_idstring · nullableOptional

Evaluate conditions as this user.

workspace_idstring · uuid · nullableOptional

Resolve name and the policy's candidate selectors in this workspace. Omit for the deployment's default workspace.

Responses
200

Successful Response

application/json

The plan a policy compiles to for the given inputs.

is_dynamicbooleanRequired
namestringRequired
router_backendstring · nullableOptional
router_candidatesstring[]Optional
selection_reasonstringRequired
post/api/v1/routing/policies/explain
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 Policy

delete

Delete a stored policy in one scope.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
namestringRequired
Query parameters
user_idstring · nullableOptional

Delete the policy scoped to this user. Omit to delete the workspace-wide one.

workspace_idstring · uuid · nullableOptional

Delete the policy in this workspace. Omit for the deployment's default workspace.

Responses
204

Successful Response

No content

delete/api/v1/routing/policies/{name}
DELETE /api/v1/routing/policies/{name} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*

No content

Recommend Model For Agent

post

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 user field is required and names who the decision is billed to.

  • API key: the decision is billed to the key's own user.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

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.

agent_typestring · min: 1 · max: 128Required

The subagent type: a built-in such as Explore or Plan, or a custom agent's name.

candidatesobject · Candidates · nullableOptional

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.

descriptionstring · max: 1024Optional

The caller's short description of the task.

Default: ""
harnessstring · enumRequired

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.

Possible values:
parent_modelstring · min: 1 · max: 256Required

The model the parent conversation runs on, as the harness names it.

promptstring · min: 1 · max: 65536Required

The task the subagent is given.

requested_modelstring · max: 256 · nullableOptional

The model the caller asked for, if any. Sent as a fact; the recommendation is the gateway's.

session_idstring · min: 1 · max: 256Required

The harness's own id for the session the spawn happens in.

tool_use_idstring · min: 1 · max: 256Required

The harness's own id for the tool call that spawns the subagent.

userstring · nullableOptional

User ID the decision is billed to when asking with the master key; not sent upstream.

Responses
200

Successful Response

application/json

The model recommended for the subagent.

modelstringRequired

A model alias or id the harness can start the subagent on.

reasonstring · nullableOptional

Why, in one short sentence the harness may show.

post/api/v1/routing/recommend
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?