HTTP API

任意のHTTPクライアントからBeam Benchを操作します。CLIが通信するものと同じインターフェースです。

HTTP APIはBeam Benchの統合インターフェースです。ほとんどのCLIコマンドと外部クライアントは、これらのルートを使用します。デスクトップフロントエンドはTauri IPCを通じて共有サービスを呼び出すため、通常の使用でHTTPサーバーを必要としません。Webアプリ、統合サーバー、モバイルアプリ、独自ツールなど、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バインディングでは、OSレベルのアクセスモデルが境界になります。マシン上のすべてのプロセスが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が返ることがあります。状態を更新し、再試行する前に変更内容を再評価してください。古いプロジェクトのスナップショットを新しい作業に盲目的に再適用しないでください。

エンドポイントグループ

Path	対象
`/api/v1/app`	アプリレベルの情報: バージョン、稼働時間、機能。
`/api/v1/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ストリーム。

リソースごとのリファレンスページは作成中です。それまではエージェント機能スキーマを参照してください。

現在のインターフェースを確認する

インストールされているバージョンが公開している内容を確認する最も速い方法です。

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で提供されます。