接口參考

會話

建立會話、發送訊息、取消執行。

POST/v1/sessions

建立會話

權限: sessions:write
限流: 60 次/分鐘
成功: 201

建立一段與 Agent 的對話。model_id、thinking_enabled、instruction、mcp_servers 在建立後不可修改，需要不同配置時請新建會話。

請求體

model_idstring必填

模型 ID，取自模型列表。

thinking_enabledboolean

是否開啟模型的思考（推理）過程，預設 true。開啟後思考內容以 agent.thinking 事件返回。

instructionstring | null

你對 Agent 的指令，例如角色、語氣、規則、領域知識，最長 100,000 字元。它附加在平台自身的系統提示詞之後，不會替換它。

mcp_serversstring[]

這個會話要使用的 MCP 伺服器 ID，最多 10 個，不能重複。需要 mcp_servers:read 權限。見 MCP 伺服器。

metadataobject

供你自己使用的鍵值對，平台不解讀。最多 16 對；鍵 1–64 字元，值為字串，最長 512 字元。常用來記錄你這邊的用戶 ID、業務單號。

回應：會話物件

idstring

會話 ID，ses_…。

statusstring

會話狀態，新建時為 IDLE。

model_idstring

建立時指定的模型。

thinking_enabledboolean

是否開啟思考。

instructionstring | null

建立時的指令。

mcp_serversstring[]

建立時指定的 MCP 伺服器。

metadataobject

你的鍵值對。

created_atstring

建立時間。

updated_atstring

最後更新時間。

錯誤

狀態碼	type	原因
422	`unknown_model`	模型不可用。`details` 中列出當前可用的模型。
404	`mcp_server_not_found`	`mcp_servers` 中有伺服器不存在或已刪除；`details` 列出所有找不到的 ID。
403	`insufficient_scope`	指定了 MCP 伺服器，但 Key 沒有 `mcp_servers:read` 權限。
422	`validation_error`	欄位缺失、超長、類型錯誤，或包含未定義的欄位。

請求

curl -s "$AXON_API/sessions" \
  -H "Authorization: Bearer $AXON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model_id": "deepseek-v4-flash",
        "thinking_enabled": true,
        "instruction": "你是一名數據分析助手，回答簡潔，結論先行。",
        "metadata": {"user": "u_42", "ticket": "T-1024"}
      }'

回應

{
  "id": "ses_8d0f3b6a2c4e4f1a9b7c5d3e1f2a4b6c",
  "status": "IDLE",
  "model_id": "deepseek-v4-flash",
  "thinking_enabled": true,
  "instruction": "你是一名數據分析助手，回答簡潔，結論先行。",
  "mcp_servers": [],
  "metadata": {"user": "u_42", "ticket": "T-1024"},
  "created_at": "2026-10-08T02:15:04.118240Z",
  "updated_at": "2026-10-08T02:15:04.118240Z"
}

GET/v1/sessions

會話列表

權限: sessions:read
成功: 200

按建立時間從新到舊返回當前項目的會話，已刪除的會話不會出現。參數見分頁。

查詢參數

limitinteger

每頁條數，1–100，預設 20。

cursorstring

上一頁回應中的 meta.next_cursor。

每個元素是會話物件。

請求

curl -s "$AXON_API/sessions?limit=20" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "items": [{"id": "ses_8d0f…", "status": "COMPLETE", "...": "..."}],
  "meta": {"next_cursor": "WyIyMDI2LTEwLTA4VDAyOjE1OjA0LjExODI0MCswMDowMCIsInNlc184ZDBm…"}
}

GET/v1/sessions/{session_id}

查詢會話

權限: sessions:read
成功: 200

返回會話物件。可以用它查看一輪是否已經結束（status 不再是 RUNNING）。

路徑參數

session_idstring必填

會話 ID。

錯誤

狀態碼	type	原因
404	`session_not_found`	會話不存在、已刪除或屬於其他項目。

請求

curl -s "$AXON_API/sessions/$SESSION" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "id": "ses_8d0f3b6a2c4e4f1a9b7c5d3e1f2a4b6c",
  "status": "COMPLETE",
  "model_id": "deepseek-v4-flash",
  "thinking_enabled": true,
  "instruction": "你是一名數據分析助手，回答簡潔，結論先行。",
  "mcp_servers": [],
  "metadata": {"user": "u_42"},
  "created_at": "2026-10-08T02:15:04.118240Z",
  "updated_at": "2026-10-08T02:15:12.904310Z"
}

PATCH/v1/sessions/{session_id}

更新會話

權限: sessions:write
限流: 60 次/分鐘
成功: 200

只能更新 metadata，會話的其他配置在建立後不可修改。更新採用合併語義（JSON Merge Patch，RFC 7396）：

請求中出現的鍵會被設定為新值，沒有出現的鍵保持不變；
鍵的值為 null 表示刪除這個鍵；
metadata 本身不能為 null；
單次請求最多 32 個鍵；合併後仍不能超過 16 對，否則返回 422 metadata_too_large。

請求體

metadataobject必填

要合併的鍵值對；值為 null 的鍵被刪除。

回應為更新後的會話物件。範例設定 ticket，刪除 user，其餘保持不變。

錯誤

狀態碼	type	原因
404	`session_not_found`	會話不存在、已刪除或屬於其他項目。
422	`metadata_too_large`	合併後超過 16 對。
422	`validation_error`	`metadata` 為 `null`，或鍵、值超出長度限制。

請求

curl -s -X PATCH "$AXON_API/sessions/$SESSION" \
  -H "Authorization: Bearer $AXON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"ticket": "T-2048", "user": null}}'

回應

{
  "id": "ses_8d0f3b6a2c4e4f1a9b7c5d3e1f2a4b6c",
  "status": "COMPLETE",
  "model_id": "deepseek-v4-flash",
  "thinking_enabled": true,
  "instruction": "你是一名數據分析助手，回答簡潔，結論先行。",
  "mcp_servers": [],
  "metadata": {"ticket": "T-2048"},
  "created_at": "2026-10-08T02:15:04.118240Z",
  "updated_at": "2026-10-08T02:20:41.337201Z"
}

DELETE/v1/sessions/{session_id}

刪除會話

權限: sessions:write
限流: 60 次/分鐘
成功: 204（無回應體）

刪除後，該會話及其事件對你不再可見，所有相關接口都返回 404。刪除不可撤銷。會話正在執行時返回 409 session_running，請先取消，等本輪結束後再刪除。刪除會話不會刪除其中交付的檔案。

路徑參數

session_idstring必填

會話 ID。

錯誤

狀態碼	type	原因
404	`session_not_found`	會話不存在、已刪除或屬於其他項目。
409	`session_running`	有一輪正在排隊或執行。

請求

curl -s -X DELETE "$AXON_API/sessions/$SESSION" -H "Authorization: Bearer $AXON_KEY"

回應

204 No Content

POST/v1/sessions/{session_id}/messages

發送訊息

權限: sessions:write
限流: 60 次/分鐘
成功: 201

發送一條用戶訊息，開始新的一輪。接口在本輪進入佇列後立即返回，不等待 Agent 處理；Agent 的處理結果透過事件串流取得。

請求體

contentstring必填

訊息內容，1–100,000 字元。首尾空白會被去掉，去掉後不能為空。

filesstring[]

要交給 Agent 的檔案 ID，最多 20 個，不能重複。需要 files:read 權限。本輪開始前，這些檔案會被放到沙箱的 /workspace/inputs/ 下，見檔案的輸入與交付。

skillsstring[]

本輪可用的技能 ID，最多 10 個，不能重複。需要 skills:read 權限。見技能。

回應是這條訊息對應的 user.message 事件，其中的 turn_id 就是本輪的 ID。

錯誤

狀態碼	type	原因
409	`session_running`	上一輪還沒有結束。等收到終止事件後再發送，或先取消上一輪。
404	`session_not_found`	會話不存在或已刪除。
404	`file_not_found`	`files` 中有檔案不存在或已刪除；`details` 列出所有找不到的 ID。
404	`skill_not_found`	`skills` 中有技能不存在或已刪除；`details` 列出所有找不到的 ID。
403	`insufficient_scope`	附帶了檔案但 Key 沒有 `files:read` 權限，或選用了技能但沒有 `skills:read` 權限。
429	`too_many_running_turns`	項目中排隊和執行中的輪次已達上限（按項目設定），`details.max_running_turns` 給出上限。等任意一輪結束後再發送。

請求

curl -s "$AXON_API/sessions/$SESSION/messages" \
  -H "Authorization: Bearer $AXON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "content": "統計 sales.csv 中各地區的銷售額，結果保存成 summary.csv 交付給我",
        "files": ["file_0c7d2e5f9a1b4c3d8e6f2a4b7c9d1e3f"]
      }'

回應

{
  "id": "evt_5b16960a81ea48d3b1142e542dd512b5",
  "type": "user.message",
  "turn_id": "turn_3f2a9c1e5b7d4e6f8a0b2c4d6e8f0a1b",
  "created_at": "2026-10-08T02:15:09.553120Z",
  "content": "統計 sales.csv 中各地區的銷售額，結果保存成 summary.csv 交付給我",
  "files": [
    {"id": "file_0c7d2e5f9a1b4c3d8e6f2a4b7c9d1e3f", "filename": "sales.csv", "mime_type": "text/csv", "size_bytes": 48213}
  ],
  "skills": []
}

POST/v1/sessions/{session_id}/cancel

取消執行

權限: sessions:write
限流: 60 次/分鐘
成功: 200

停止會話當前的一輪。無請求體，返回會話物件，可以安全地重複調用。

本輪所處階段	效果
還在排隊	立即取消。回應中會話狀態為 `CANCELLED`，事件串流收到 `turn.cancelled`，其中 `usage` 為 `null`。
正在執行	回應中會話仍是 `RUNNING`。Agent 在下一步停止，正在執行的工具會被中止；隨後事件串流收到 `turn.cancelled`，會話變為 `CANCELLED`。通常一兩秒內停止，最遲約 20 秒。
會話沒有在執行	不做任何改變，原樣返回會話。

錯誤

狀態碼	type	原因
404	`session_not_found`	會話不存在、已刪除或屬於其他項目。

請求

curl -s -X POST "$AXON_API/sessions/$SESSION/cancel" -H "Authorization: Bearer $AXON_KEY"

回應

{
  "id": "ses_8d0f3b6a2c4e4f1a9b7c5d3e1f2a4b6c",
  "status": "RUNNING",
  "model_id": "deepseek-v4-flash",
  "thinking_enabled": true,
  "instruction": "你是一名數據分析助手，回答簡潔，結論先行。",
  "mcp_servers": [],
  "metadata": {"user": "u_42"},
  "created_at": "2026-10-08T02:15:04.118240Z",
  "updated_at": "2026-10-08T02:15:09.553120Z"
}