HTTP API

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

HTTP APIは、Beam Benchとの統合インターフェースです。デスクトップアプリ、CLI、外部クライアントはすべて同じルートに接続します。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": "InvalidInput",
    "message": "Human-readable summary of what went wrong.",
    "details": { "...optional structured context..." }
  }
}

error.codeには次のいずれかが入ります。

コード	HTTP	意味
`NotFound`	404	要求されたリソースが存在しません。
`InvalidInput`	400	リクエスト本文またはパラメーターの形式が不正、または拒否されました。
`InvalidState`	412	アプリがこの操作を実行できる状態ではありません（例: プロジェクトが開かれていない）。
`Busy`	409	競合する操作がすでに進行中です。
`Conflict`	409	最後に読み取ってから、別の書き込み元がリソースを変更しました。
`StaleRevision`	412	リビジョントークンが現在のものより古い状態です。再読み込みして再試行してください。
`MachineIo`	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です。

エンドポイントグループ

パス	対象
`/api/v1/app`	アプリレベルの情報: バージョン、稼働時間、機能。
`/api/v1/agent`	エージェントの機能スキーマ、状態スナップショット、操作ガイド。
`/api/v1/projects`	開く、保存、閉じる。レイヤー、オブジェクト、取り消し/やり直し。
`/api/v1/projects/import`	SVG、DXF、PDF、AI、ラスター画像をプロジェクトにインポート。
`/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で提供されます。