Key Orchestrator Graph

GET

api

keys

{id}

orchestrator-graph

Key Orchestrator Graph

curl --request GET \
  --url https://api.example.com/api/v1/keys/{id}/orchestrator-graph \
  --header 'Content-Type: application/json' \
  --data '
{
  "enabled": true,
  "nodes": [
    {}
  ],
  "edges": [
    {}
  ]
}
'

import requests

url = "https://api.example.com/api/v1/keys/{id}/orchestrator-graph"

payload = {
    "enabled": True,
    "nodes": [{}],
    "edges": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({enabled: true, nodes: [{}], edges: [{}]})
};

fetch('https://api.example.com/api/v1/keys/{id}/orchestrator-graph', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/keys/{id}/orchestrator-graph",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'enabled' => true,
    'nodes' => [
        [
                
        ]
    ],
    'edges' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/keys/{id}/orchestrator-graph"

	payload := strings.NewReader("{\n  \"enabled\": true,\n  \"nodes\": [\n    {}\n  ],\n  \"edges\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/keys/{id}/orchestrator-graph")
  .header("Content-Type", "application/json")
  .body("{\n  \"enabled\": true,\n  \"nodes\": [\n    {}\n  ],\n  \"edges\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/keys/{id}/orchestrator-graph")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"enabled\": true,\n  \"nodes\": [\n    {}\n  ],\n  \"edges\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "key_id": "<string>",
  "graph": {}
}

The orchestrator graph is a runnable per-key flow: Entry → Classifier / Router → Model → Guardrail. When enabled, every request to the key runs the path you drew — routing, model selection, per-node skills, and guardrails all applied. It takes precedence over the model plan and applies on both the native and OpenAI-compatible endpoints. This is the REST surface behind the dashboard’s Orchestrator canvas and the MCP configuration tools.

Authentication

Requires an API key with billing scope; the caller must own the key.

Path Parameters

string

required

The API key UUID.

Get the graph

GET /api/v1/keys/{id}/orchestrator-graph

string

The API key UUID.

object | null

The saved graph ({ version, enabled, nodes, edges }) or null when none is set.

Replace the graph

PUT /api/v1/keys/{id}/orchestrator-graph

boolean

required

When true, the orchestrator runs this graph. An enabled graph must have an entry node and at least one model node with an engine, or the request is rejected.

object[]

required

Up to 100 nodes. Each: { id, type, position?, config? }. type is one of entry, classifier, router, model, guardrail, description, output. A model node’s config.upstreamId is its engine; a guardrail node’s config.guardrailPolicyId is its policy (before the model = screens input, after = screens output).

object[]

required

Each: { id, source, target, modes?, when?, default? }. Classifier branches use modes (the mode that takes the edge); Router branches use when (keywords); default is the fallback edge.

Example

curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/orchestrator-graph \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "nodes": [
      { "id": "entry", "type": "entry", "config": { "label": "User Prompt" } },
      { "id": "classifier", "type": "classifier", "config": { "label": "Classifier" } },
      { "id": "m_fast", "type": "model", "config": { "upstreamId": "arca-velox-5.1", "label": "fast" } },
      { "id": "m_think", "type": "model", "config": { "upstreamId": "arca-magnus-5.1", "label": "think" } }
    ],
    "edges": [
      { "id": "e_in", "source": "entry", "target": "classifier" },
      { "id": "e_fast", "source": "classifier", "target": "m_fast", "modes": ["fast"] },
      { "id": "e_think", "source": "classifier", "target": "m_think", "modes": ["think"] }
    ]
  }'

await theo.keys.setOrchestratorGraph("KEY_ID", { enabled: true, nodes, edges });

Key Orchestrator Graph

curl --request GET \
  --url https://api.example.com/api/v1/keys/{id}/orchestrator-graph \
  --header 'Content-Type: application/json' \
  --data '
{
  "enabled": true,
  "nodes": [
    {}
  ],
  "edges": [
    {}
  ]
}
'

import requests

url = "https://api.example.com/api/v1/keys/{id}/orchestrator-graph"

payload = {
    "enabled": True,
    "nodes": [{}],
    "edges": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({enabled: true, nodes: [{}], edges: [{}]})
};

fetch('https://api.example.com/api/v1/keys/{id}/orchestrator-graph', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/keys/{id}/orchestrator-graph",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'enabled' => true,
    'nodes' => [
        [
                
        ]
    ],
    'edges' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/keys/{id}/orchestrator-graph"

	payload := strings.NewReader("{\n  \"enabled\": true,\n  \"nodes\": [\n    {}\n  ],\n  \"edges\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/keys/{id}/orchestrator-graph")
  .header("Content-Type", "application/json")
  .body("{\n  \"enabled\": true,\n  \"nodes\": [\n    {}\n  ],\n  \"edges\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/keys/{id}/orchestrator-graph")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"enabled\": true,\n  \"nodes\": [\n    {}\n  ],\n  \"edges\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "key_id": "<string>",
  "graph": {}
}

Overview

Completions

Media Generation

Audio

Skills API

E.V.I. Canvas

Workflows

Hooks

Settings

Embed Widgets

Guardrails

Routing Studio

Theo Browser

Benchmarks

Webhooks

Billing

Resources

Authentication

Path Parameters

Get the graph

Replace the graph

Example

​Authentication

​Path Parameters

​Get the graph

​Replace the graph

​Example

Authentication

Path Parameters

Get the graph

Replace the graph

Example