Sign in
routing

Explain Policy

Changed on

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.

post/api/v1/routing/policies/explain

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header Otari-Key
    • API key in header x-api-key

Request body

allowed_modelsstring[] nullable

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

budget_remaining_usdnumber nullable

Simulated budget remaining, USD.

budget_used_pctnumber nullable

Simulated budget usage percentage.

key_idstring nullable

Evaluate conditions as this API key id.

namestring nullable

An existing policy to explain.

specobject nullable

An unsaved policy body to explain.

user_idstring nullable

Evaluate conditions as this user.

workspace_idstring uuid nullable

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

Response

Successful Response

guardrailsobject[] required
is_dynamicboolean required
namestring required
router_backendstring nullable
router_candidatesstring[]
router_weightsobject

For a weighted policy, the percentage of traffic each candidate receives, normalized over the candidates this caller may use. Empty for every other policy, and for a weighted policy whose whole split this caller may not use: a split over no candidate is not a split, and each filtered candidate is named in dropped instead. A weighted split needs no request state, so unlike a learned router's ranking it is knowable here: the plan above is the real ordering by share, not the decline path.

selection_reasonstring required

Changes