API 概要

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

基準アドレス

Studio API は /api/v1 です。

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

旧パス /api/... も 引き続き動作します(エイリアス)。このドキュメントの例でまだ /api/... と記載されているものも そのまま使用できますが、新しく作成するコードは /api/v1 で記述してください。

プラットフォームの v5 と混同しないでください

同じ API の 2 つのバージョンではなく、別の製品であり、リスナーも異なります。

	内容	パス
Studio API	Studio 自身の API (このドキュメント)	/api/v1
プラットフォーム API	Studio が作成したアプリが自身のオリジンから呼び出すプロキシ	/api/v5

認証

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

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 プラットフォームデータ探索、セマンティック検索
管理	設定・ユーザー・ウォッチャー・監査・通知