ReferenceAPI reference
Policies
declarative routing policies with versions, canary and shadow (M3)
GET
/v1/policiesAuthorization
bearer AuthorizationBearer <token>
In: header
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/policies"{ "object": "list", "data": [ { "name": "default", "version": 3, "status": "active", "created_at": "2026-11-01T10:00:00Z" } ]}POST
/v1/policiesAuthorization
bearer AuthorizationBearer <token>
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/policies" \ -H "Content-Type: application/json" \ -d '{ "name": "cheap-first", "yaml": "version: 1\\nsort: price\\n" }'{ "name": "cheap-first", "version": 1, "status": "draft", "yaml": "version: 1\nsort: price\n", "created_at": "2026-11-02T10:00:00Z"}POST
/v1/policies/validateAuthorization
bearer AuthorizationBearer <token>
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/policies/validate" \ -H "Content-Type: application/json" \ -d '{ "yaml": "policy: acme-default\\nversion: 7\\ndefaults: { sort: price }\\n" }'{ "valid": false, "path": "/rules/0/match", "message": "undeclared reference to 'request'"}POST
/v1/policies/{name}/dry-runAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/policies/string/dry-run" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v3.2", "est_input_tokens": 60000 }'{ "policy": "acme-default", "version": 7, "decision": { "sort": "latency", "affinity": "auto", "max_attempts": 3, "notes": [ "rule big-context-goes-to-fast-hosts applied" ] }, "plan": [ { "attempt": 1, "endpoint_id": "ep_deepinfra_deepseek-v3.2_us", "provider": "deepinfra", "region": "us", "est_cost_micro": 3564, "reason": "native" } ], "trace": "model deepseek/deepseek-v3.2 (active) … sort: latency"}GET
/v1/policies/{name}/canariesAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/policies/string/canaries"{ "object": "list", "data": [ { "version": 7, "endpoint_id": "ep_newhost_deepseek-v3.2_us", "state": "green", "error_rate": 0.004, "samples": 1204, "max_error_rate": 0.02, "min_samples": 200, "reason": "error rate 0.40 % over 1204 attempts is within 2.00 %", "evaluated_at": "2026-09-10T09:00:00Z" } ]}GET
/v1/policies/{name}/shadowsAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/policies/string/shadows"{ "object": "list", "data": [ { "shadow_endpoint": "ep_newhost_deepseek-v3.2_us", "primary_endpoint": "ep_deepinfra_deepseek-v3.2_us", "policy_version": 7, "runs": 412, "errors": 3, "stop_mismatch": 11, "primary_cost_micro": 148200, "shadow_cost_micro": 131900, "cost_delta_micro": -16300, "primary_ttft_ms": 640.2, "shadow_ttft_ms": 588.9, "bill": "platform" } ]}GET
/v1/policies/{name}/experimentsAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Query Parameters
hours?integer
Range
1 <= value <= 720Default
24Response Body
application/json
application/json
curl -X GET "https://example.com/v1/policies/string/experiments"{ "object": "list", "hours": 24, "data": [ { "arm": "control", "experiment": "sonnet-vs-deepseek", "requests": 8120, "errors": 22, "cost_micro": 1204500, "ttft_p50_ms": 610, "ttft_p95_ms": 1480, "output_tokens": 2210400 }, { "arm": "candidate", "experiment": "sonnet-vs-deepseek", "requests": 903, "errors": 4, "cost_micro": 98200, "ttft_p50_ms": 540, "ttft_p95_ms": 1310, "output_tokens": 244100 } ]}GET
/v1/policies/{name}/versionsAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Response Body
application/json
application/json
curl -X GET "https://example.com/v1/policies/string/versions"{ "object": "list", "data": [ { "name": "default", "version": 3, "status": "active", "created_at": "2026-11-01T10:00:00Z" } ]}POST
/v1/policies/{name}/versionsAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/policies/string/versions" \ -H "Content-Type: application/json" \ -d '{ "yaml": "version: 1\\nsort: latency\\n" }'{ "name": "default", "version": 4, "status": "draft", "yaml": "version: 1\nsort: latency\n", "created_at": "2026-11-03T10:00:00Z"}POST
/v1/policies/{name}/activateAuthorization
bearer AuthorizationBearer <token>
In: header
Path Parameters
name*string
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
curl -X POST "https://example.com/v1/policies/string/activate" \ -H "Content-Type: application/json" \ -d '{ "version": 4, "scope": { "project_id": "prj_01J9ZK2K4Q7Q3M3QX1V0F1PRJ1" } }'{ "name": "default", "version": 4, "status": "active", "created_at": "2026-11-03T10:00:00Z"}