Create a dynamic route
curl --request POST \
--url https://api.opper.ai/management/v1/dynamic-routes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>"
}
'import requests
url = "https://api.opper.ai/management/v1/dynamic-routes"
payload = { "name": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>'})
};
fetch('https://api.opper.ai/management/v1/dynamic-routes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"draft": {
"graph": {},
"layout": {},
"revision": 123,
"validation": "<array>"
},
"route": {
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"display_name": "<string>",
"draft_revision": 123,
"invocation_model": "<string>",
"name": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"deleted_at": "2023-11-07T05:31:56Z",
"draft_graph": {},
"draft_layout": {},
"draft_validation": "<array>"
},
"version_count": 123,
"active_version": {
"created_at": "2023-11-07T05:31:56Z",
"note": "<string>",
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version_number": 123
},
"latest_version_number": 123
},
"meta": {
"deployed_version": {
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"draft_revision": 123,
"note": "<string>",
"route_name": "<string>",
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version_number": 123,
"graph": {},
"layout": {},
"validation": "<array>"
},
"model_access_locks": {
"locked_projects": 123,
"message": "<string>",
"project_uuids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}{
"error": "<string>",
"required_scope": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}Management
Create a dynamic route
Creates a route draft. Omit graph to seed a complete default graph, then use data.draft.graph as a starting point. Empty graphs are invalid. Omit deploy or set deploy=false to keep the route unpublished; deploy=true changes live routing immediately. Review data.draft.validation, save changes with update_dynamic_route_draft, then use simulate_dynamic_route without version_number to test the draft before deploy_dynamic_route. Optional display_name is a human label separate from the route identifier; it preserves case and spaces. Invoke a deployed route with model=dynamic/<name>; invocation_model contains the exact string. Requires the `dynamic_routes:write` scope.
Graph format: an object with an `elements` array. Each element has a unique `id`, a `type`, optional `properties`, and `outputs`, an object mapping output names to `{"elementId":"target-node-id"}`. Include `id: START, type: start` and `id: END, type: end`; `input` and `output` are not node types. A minimal deployable graph (replace the model with an available catalog ID permitted by your policy):
```json
{"elements":[{"id":"START","type":"start","outputs":{"next":{"elementId":"primary"}}},{"id":"primary","type":"model","properties":{"model":"cerebras/gpt-oss-120b"},"outputs":{"success":{"elementId":"END"},"fallback":{"elementId":"END"}}},{"id":"END","type":"end","outputs":{}}]}
```
Supported node types and properties:
- `start`: the START node; `outputs.next` selects the first node.
- `end`: the END node; `outputs` is `{}`.
- `model`: `properties.model` is a catalog model ID. `outputs.success` targets END or an observe node; `outputs.fallback` targets another model, pool, or END.
- `pool`: `properties.models` contains 2-10 `{model,metrics}` candidates; `properties.expression` is a numeric CEL expression such as `model.cost`, sorted ascending. Uses the same success/fallback outputs as model.
- `conditional`: `properties.cases` contains `{id,expression}` entries; each expression is a CEL predicate over `metadata`, `auth`, and `input`. Connect an output for each case ID and a `default` output. The first true case wins.
- `percentage`: `properties.buckets` contains at least two `{id,weight}` entries with positive integer weights totaling 100. Connect an output for each bucket ID.
- `classifier`: `properties.cases` contains 2-10 `{id,label,instructions}` entries with unique labels, plus optional `context` and `model` properties. Connect an output per case ID; no default output. Classification failures fail the route.
- `observe`: `properties.criteria` defines an asynchronous evaluation, with optional `score_type` (`score` or `binary`), `model`, `threshold`, and `sample_rate` (both greater than 0 and at most 1). Place after model/pool success or another observe node; `outputs.next` leads to another observe node or END.
Graphs must be acyclic. Every node except END accepts at most one incoming edge; use separate model nodes on separate branches. Deployment requires each path from START to reach a model or pool before END. The route name is the model identifier on chat completions, responses, messages and native calls.
POST
/
management
/
v1
/
dynamic-routes
Create a dynamic route
curl --request POST \
--url https://api.opper.ai/management/v1/dynamic-routes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>"
}
'import requests
url = "https://api.opper.ai/management/v1/dynamic-routes"
payload = { "name": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>'})
};
fetch('https://api.opper.ai/management/v1/dynamic-routes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": {
"draft": {
"graph": {},
"layout": {},
"revision": 123,
"validation": "<array>"
},
"route": {
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"display_name": "<string>",
"draft_revision": 123,
"invocation_model": "<string>",
"name": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"deleted_at": "2023-11-07T05:31:56Z",
"draft_graph": {},
"draft_layout": {},
"draft_validation": "<array>"
},
"version_count": 123,
"active_version": {
"created_at": "2023-11-07T05:31:56Z",
"note": "<string>",
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version_number": 123
},
"latest_version_number": 123
},
"meta": {
"deployed_version": {
"created_at": "2023-11-07T05:31:56Z",
"description": "<string>",
"draft_revision": 123,
"note": "<string>",
"route_name": "<string>",
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version_number": 123,
"graph": {},
"layout": {},
"validation": "<array>"
},
"model_access_locks": {
"locked_projects": 123,
"message": "<string>",
"project_uuids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}{
"error": "<string>",
"required_scope": "<string>"
}{
"error": "<string>"
}{
"error": "<string>"
}{
"error": {
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
},
"meta": {}
}Authorizations
Management API authentication. Pass an op-mak-… management token as a Bearer token. Runtime op-… API keys are rejected with 403 — they belong on the data-plane endpoints. Mint a management key from the platform UI under Settings → API keys.
Body
application/json
Route name; callers invoke the route as dynamic/. Lowercase letters and digits plus '.' '_' '-'; up to 128 characters; unique per organization.
When true the draft is validated and deployed as version 1 in the same call; the response then carries deployed_version in meta.
Free-text description shown in the platform.
Optional human label; preserves case and spaces. Empty uses the route identifier. Editable without deploying.
Maximum string length:
128Routing graph object with elements. Each node has id, type, outputs mapping output names to {elementId: targetID}, and optional properties. Include START/start and END/end. Supported types: start, end, model, pool, conditional, percentage, classifier, observe. Omit graph on create to seed a default; copy its returned draft.graph to customize. See tool description for node properties and topology.
Show child attributes
Show child attributes
Example:
{
"elements": [
{
"id": "START",
"outputs": { "next": { "elementId": "model_default" } },
"type": "start"
},
{
"id": "model_default",
"outputs": {
"fallback": { "elementId": "END" },
"success": { "elementId": "END" }
},
"properties": {
"label": "Default model",
"model": "cerebras/gpt-oss-120b"
},
"type": "model"
},
{ "id": "END", "outputs": {}, "type": "end" }
]
}
Editor canvas positions keyed by element id. Opaque to the gateway; omit when authoring from code.
Release note recorded on the deployed version. Only read when deploy is true.
Last modified on September 17, 2026