導入 API

デプロイメント サーフェスは、プレビュー ビルド、本番環境のパブリッシュ、パイプライン イベント ストリームをカバーします。パスにはプレフィックスは付けられず、ルートは https://api.showly.ai になります (バージョンのプレフィックスはありません)。

デプロイメントを作成する

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "preview",
  "commitSha": "abc123...",
  "branch": "main"
}

これは、デプロイメントを作成する唯一のルートです (パス内に siteId があり、POST /deployments はありません)。 Idempotency-Key ヘッダーが必要です。キーが欠落している場合は 428 が返され、再実行されたキーが競合している場合は 409 が返されます。 202 + queued 状態の展開レコードを返します。ビルドは非同期で実行されます。イベントをサブスクライブするか、デプロイメント・レコードをポーリングします。

{
  "ok": true,
  "data": {
    "id": "8c9d3e2a-4f1b-4c6d-9a2e-1f0b3c4d5e6f",
    "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target": "preview",
    "status": "queued",
    "createdAt": "2026-05-14T15:00:00Z"
  }
}

デプロイメント レコードの環境フィールドの名前は target で、preview、staging、または production のいずれかです。

運用環境に公開する

運用パブリッシュは、プロモートされる既に構築された ready プレビューに名前を付ける environment: "production" と sourceDeploymentId を持つ同じエンドポイントを使用します。

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "production",
  "sourceDeploymentId": "dep_01HZX..."
}

実稼働公開には OTP または MFA 登録は必要ありません。まだ必要です 明示的な公開アクション、およびワークスペースに approvalWorkflows がある場合 有効、二人称承認。エージェントはそのような場合に request_publish を使用します ポリシーが有効であるか、そうでない場合は 2 段階の publish_site 確認が行われます。

デプロイメントを取得する

GET /deployments/{deploymentId}

デプロイメント ステータスは、次の 5 つの値のいずれかになります。

queued → building → ready
                  ↘ failed
                  ↘ canceled

ready は、プレビュー展開と運用展開の両方の最終的な成功状態です。 failed と canceled は端末障害状態です。 built または live ステータスはありません。 ready プレビュー展開では、そのアドレスが url フィールドに含まれます。 ready 実稼働デプロイメントは、サイトの実稼働ルートにサービスを提供します。

ビルドの進行状況をストリーム配信する

ライブ ビルドの進行状況は、プレビュー サーフェスから SSE 経由でストリーミングされます。

GET /previews/{deploymentId}/stream
Accept: text/event-stream

ストリームはステータス遷移を生成し、デプロイメントが最終状態に達すると閉じます。ポストホック読み取りの場合、2 つのプレーン エンドポイントでほとんどのニーズをカバーできます。

• GET /deployments/{deploymentId}/log?lineCount=200 — キャプチャされたビルド ログの末尾。
• GET /deployments/{deploymentId}/diagnostics — エージェントのセルフデバッグ用に設計された構造化された障害バンドル (ステージ、エラー コード、ログテール、ランク付けされた仮説)。

本番公開リクエストを承認/拒否する

POST /approvals/{requestId}/decision
Content-Type: application/json

{
  "decision": "approve" | "reject",
  "notes": "looks good"
}

許可された承認ロールを持つアクティブなユーザー メンバーシップが必要です。発信側アクターは自身のリクエストを承認することを禁止されています（職務の分離）。

ロールバック

ロールバック REST エンドポイントはありません。以前の展開に戻すことは、Web-UI 操作のみです。以前の ready プレビューを再公開するには、environment: "production" を指定して POST /sites/{siteId}/deploy を呼び出し、そのデプロイメントの ID を sourceDeploymentId にします。通常の承認、クォータ、およびセキュリティ ゲートは引き続き適用されますが、OTP 登録は必要ありません。

デプロイメントのリストを表示する

GET /deployments

ワークスペースの完全な展開リストをプレーンな配列として返します。フィルターやページネーションのパラメーターはまだありません。単一サイトの履歴については、GET /sites/{siteId}/deployments を使用します。

デプロイメントに固有のエラー

月次デプロイ クォータを使い果たすと、クォータ エラーで 402 が返されます。プランをアップグレードするか、月次リセットを待ちます。

パターン

展開が完了するまで待ちます (CI):

DEP=$(curl ... | jq -r .data.id)
while :; do
  S=$(curl -sS .../deployments/$DEP | jq -r .data.status)
  [ "$S" = "ready" ] && break
  { [ "$S" = "failed" ] || [ "$S" = "canceled" ]; } && exit 1
  sleep 10
done

ビルド ログを読んでください:

curl -sS ".../deployments/$DEP/log?lineCount=500" \
  | jq -r '.data.lines[]' | tee build.log

ほとんどの自動化では、MCP create_preview ツール の方が簡単です。MCP が適合しない場合には、REST API が存在します。