> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 密鑰編排器圖

> 讀取或替換某個密鑰的可執行編排器圖——入口 → 分類器/路由器 → 模型 → 護欄。

編排器圖是一個按密鑰運行的可執行流程：`Entry → Classifier / Router → Model → Guardrail`（入口 → 分類器 / 路由器 → 模型 → 護欄）。當 `enabled` 為真時，發往該密鑰的每一次請求都會沿着你繪製的路徑運行——路由、模型選擇、各節點技能以及護欄都會一併生效。它的優先級高於[模型方案](/api-reference/keys/model-plan)，並且在原生端點和兼容 OpenAI 的端點上**同時**生效。

這是儀表盤中編排器畫布以及 [MCP 配置工具](/mcp/tools)背後的 REST 接口。

## 身份驗證

需要擁有 `billing` 權限範圍的 API 密鑰；調用方必須是該密鑰的所有者。

## 路徑參數

<ParamField path="id" type="string" required>API 密鑰的 UUID。</ParamField>

## 獲取圖

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

<ResponseField name="key_id" type="string">API 密鑰的 UUID。</ResponseField>
<ResponseField name="graph" type="object | null">已保存的圖（`{ version, enabled, nodes, edges }`），若未設置則為 `null`。</ResponseField>

## 替換圖

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

<ParamField body="enabled" type="boolean" required>
  為 `true` 時，編排器將運行該圖。啓用的圖**必須**包含一個 `entry` 節點，以及至少一個帶有引擎的 `model` 節點，否則請求會被拒絕。
</ParamField>

<ParamField body="nodes" type="object[]" required>
  最多 100 個節點。每個節點的結構為：`{ id, type, position?, config? }`。`type` 取值為 `entry`、`classifier`、`router`、`model`、`guardrail`、`description`、`output` 之一。模型節點的 `config.upstreamId` 即其引擎；護欄節點的 `config.guardrailPolicyId` 即其策略（位於模型之前 = 審查輸入，之後 = 審查輸出）。
</ParamField>

<ParamField body="edges" type="object[]" required>
  每條邊的結構為：`{ id, source, target, modes?, when?, default? }`。分類器分支使用 `modes`（該邊所對應的模式）；路由器分支使用 `when`（關鍵詞）；`default` 為回退邊。
</ParamField>

## 示例

<CodeGroup>
  ```bash curl theme={null}
  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"] }
      ]
    }'
  ```

  ```ts SDK theme={null}
  await theo.keys.setOrchestratorGraph("KEY_ID", { enabled: true, nodes, edges });
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.