HTTP API

HTTP API 是 Beam Bench 的整合介面。大多數 CLI 命令和外部用戶端都會使用這些路由。桌面前端透過 Tauri IPC 呼叫共用服務，正常使用時不需要 HTTP 伺服器。如果你有需要在非 CLI 環境中使用 Beam Bench 的情境，例如網頁應用程式、整合伺服器、行動應用程式或自有工具，請直接使用 API。

API 隨桌面應用程式提供，並在程序內執行。不需要另外安裝服務。

預設值與安全性

在目前版本中，本機 API 伺服器使用以下設定：

本機 API：關閉。
API 連接埠：5900。
允許網路裝置連線：關閉。啟用 API 後，伺服器會繫結至127.0.0.1，只接受來自這臺電腦的連線。

你主動啟用前，API 不會接聽連線。啟用網路存取需要另外主動選取，因為 API 未經驗證，且包含可移動機器和啟動雷射的操作。

若要使用 API，請從設定 → 一般變更設定：

開啟桌面應用程式。
編輯 → 設定 → 一般。
開啟本機 API。
除非另一臺受信任的裝置必須連線，否則請保持關閉允許網路裝置連線。

變更會立即生效，不需要重新啟動。

基本 URL

http://<host>:5900/api/v1

當允許網路裝置連線關閉時，<host>是localhost（或127.0.0.1）。開啟時，網路上的任何裝置都可以透過機器的 LAN IP 連線至伺服器。

連接埠可在設定 → 一般中設定，5900 是預設值。

驗證

無。API 沒有權杖、金鑰或登入功能。

使用 localhost 繫結時，作業系統層級的存取模型就是邊界：你機器上的任何程序都可以與 API 通訊。
啟用網路繫結後，同一網路上的任何人都可以與 API 通訊。請勿在不受信任的 Wi-Fi 上使用網路繫結模式。

請求格式

所有 POST/PATCH/PUT 內容都是 JSON：

Content-Type: application/json

查詢字串是扁平的 key=value。路徑區段會依通常方式進行 URL 編碼。

回應封裝

成功回應會直接回傳資源內容，不使用包裝器：

{
  "field": "value",
  "...": "..."
}

錯誤會回傳統一的封裝格式：

{
  "error": {
    "code": "invalid_input",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.code的值可以是：

Code	HTTP	意義
`not_found`	404	要求的資源不存在。
`invalid_input`	400	請求內容或參數格式錯誤，或遭到拒絕。
`invalid_state`	412	應用程式目前的狀態不適合執行此操作，例如沒有開啟專案。
`busy`	409	衝突的操作已在進行中。
`conflict`	409	自上次讀取後，另一個寫入者已變更資源。
`stale_revision`	412	你的修訂權杖落後於目前版本。請重新讀取後重試。
`machine_io`	502	機器連線失敗，例如中斷、逾時或傳輸錯誤。
`persistence`	500	磁碟寫入或讀取失敗。
`internal`	500	未預期的伺服器錯誤。請回報為錯誤。

需要確認的錯誤

少數操作可以移動機器或啟動雷射。這些端點要求在請求內容中明確設定確認旗標。若缺少旗標，API 會回傳428 Precondition Required：

{
  "error_code": "CONFIRMATION_REQUIRED",
  "missing": ["confirm_motion"],
  "message": "This command can move the machine and requires explicit confirmation."
}

請將指定旗標設為true後重新傳送請求。目前使用的旗標是confirm_motion、confirm_laser_on、confirm_raw_gcode和confirm_air_assist。

並行專案編輯

設計交易會在提交時比對其擷取的專案。並行編輯、切換專案或關閉專案都可能回傳stale_revision。請重新整理狀態，重新評估變更後再重試。請勿直接將較舊的專案快照重播到較新的工作上。

端點群組

路徑	涵蓋內容
`/api/v1/app`	應用程式層級資訊：版本、執行時間、功能。
`/api/v1/agent`	Agent 功能結構描述、狀態快照和操作指南。
`/api/v1/projects`	開啟、儲存、關閉。圖層、物件、復原和重做。
`/api/v1/projects/import`	匯入 LightBurn、SVG、DXF、PDF、AI、EPS 和點陣檔案。另有專用路由處理受限的 G-code 幾何匯入。
`/api/v1/export`	將專案轉譯為 SVG、DXF、PDF、EPS、AI。
`/api/v1/design`	描述目前設計、轉譯為 PNG、套用交易式編輯。
`/api/v1/preview`	產生切割預覽和統計資料。
`/api/v1/jobs`	預檢、執行、乾跑、暫停、繼續、框選、停止。
`/api/v1/machine`	連線、中斷連線、狀態、點動、歸零。
`/api/v1/camera`	裝置、狀態、擷取、覆疊（顯示、轉換、轉譯）、校正、對齊。
`/api/v1/console`	傳送原始 G-code。讀取最近的主控臺記錄。
`/api/v1/macros`	列出、儲存和執行使用者巨集。
`/api/v1/materials`	材料庫：以材料和厚度為索引的預設值。
`/api/v1/profiles`	機器設定檔：建立、列出、套用。
`/api/v1/assets`	圖庫資產存取。
`/api/v1/vector`	向量操作：轉換、布林、群組、路徑。
`/api/v1/events`	狀態變更和機器事件的 WebSocket 串流。

各資源的參考頁面仍在製作中，目前請參閱 Agent 功能結構描述。

探索即時介面

查看已安裝版本公開內容的最快方式：

curl -s http://localhost:5900/api/v1/agent/capabilities | jq .

這會回傳完整的功能結構描述，包括每個端點、其參數和回應形狀。結構描述是權威說明，本頁則是其指南。

若要檢查狀態：

curl -s http://localhost:5900/api/v1/agent/state | jq .

若要取得如何操作應用程式的文字說明：

curl -s http://localhost:5900/api/v1/agent/guide

版本控制

所有路由都位於/api/v1下。發生重大變更時，會放入/api/v2。增量變更，例如新端點和新的選用欄位，會在v1中提供，不會提升版本。