Sign in
routing

Explain Policy

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/v1/routing/policies/explain

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

Changed in 4 of the 142 revisions of this API.5

  • daef1d31b5d11See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • 7785ed2d26ec1See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 9960db758c292See the full diff
    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • 00866b0c54071See the full diff
    • ○

      endpoint added

      endpoint-added