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>",
      "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>"
    }
  }
}

{
  "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. 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

dynamic-routes

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>",
      "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>"
    }
  }
}

{
  "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

Authorization

string

header

required

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

name

string

required

Route name; callers invoke the route as dynamic/. Lowercase letters and digits plus '.' '_' '-'; up to 128 characters; unique per organization.

deploy

boolean

When true the draft is validated and deployed as version 1 in the same call; the response then carries deployed_version in meta.

description

string

Free-text description shown in the platform.

graph

object

Routing 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

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" }
  ]
}

layout

object

Editor canvas positions keyed by element id. Opaque to the gateway; omit when authoring from code.

note

string

Release note recorded on the deployed version. Only read when deploy is true.

Response

Successful response

data

object

Show child attributes

Compatibility

Multimodality

Files

Realtime

Roundtable

Platform APIs

Create a dynamic route

Authorizations

Body

Response