API 概要

Studio サーバーは、Web UI が使用しているものと同じ REST API を公開しています。本ドキュメントは、この API を直接呼び出す統合開発者向けです。

ベースアドレス

すべてのパスは、Studio サーバーアドレス配下の /api で始まります。

https://<studio-host>/api/...

認証

セッショントークンをヘッダーで送信します。

Authorization: Bearer <token>

トークンがない場合や期限切れの場合、サーバーは 401 を返します。Web UI は 401 を受け取ると保存済みトークンを破棄し、ログイン画面に戻ります。直接呼び出す場合も同じ処理を推奨します — 401 は再試行では解決しません。

レスポンス形式

成功レスポンスは data エンベロープに格納されて返されます。

{
  "data": { "id": "prj_01H...", "name": "라인 모니터" }
}

失敗レスポンスは errors 配列を含みます。先頭要素の message が、人間が読むためのメッセージです。

{
  "errors": [
    { "code": "project_not_found", "message": "프로젝트를 찾을 수 없습니다." }
  ]
}

クライアントは HTTP ステータスと errors[0].message を併せて確認するのが安全です。サーバーがメッセージを返さない場合があるため、Web UI はそのときのみ独自のフォールバック文言を使用します。

ストリーミングイベント

エージェントが作業している間の進行状況は ストリーミングで送られます。対話(/api/session/{id}/message、/api/ask)と通知(/api/notifications/stream)がこれに該当します。

イベントは次の 7 種類です。

type	含まれる値	意味
assistant_text	text	エージェントが書いたテキスト断片
tool_call	name, input	ツールを呼び出した
tool_result	name, ok, summary	ツール結果。ok が成否
file_change	path	ファイルが変更された
commit	hash, message	変更がコミットされた
done	—	今回のターンが終了した
error	message	処理中のエラー

done または error が来るまで読み続ければよいです。

添付

画像などの添付は base64 でインライン送信します。

{
  "name": "설비사진.png",
  "mime": "image/png",
  "dataBase64": "iVBORw0KGgo..."
}

ドキュメント構成

ドキュメント	扱う内容
セッション	作業セッションのライフサイクル、ファイル・履歴・元に戻す
プロジェクトとデプロイ	アプリの作成・デプロイ・ロールバック・ランタイム
対話	エージェントとの対話、クエリ履歴
スキル	現場スキルの登録・抽出・インポート
プラットフォーム連携	PlantPulse プラットフォームのデータ探索、セマンティック検索
管理	設定・ユーザー・ウォッチャー・監査・通知