公開 API 概要
MCP サーフェスの代わりに REST API を直接使用する場合。
Showly のパブリック REST API は、MCP サーフェスが適合しない場合 (CI スクリプト、カスタム ダッシュボード、エージェントではないサードパーティ統合など) のために存在します。
エージェントを実装している場合は、MCP を使用してください。 MCP には監査、スコープ付きトークン、型付きツールスキーマが組み込まれています。REST API でも同じ操作を実行できますが、人が管理する自動化を想定した、より汎用的なインターフェースです。
ベース URL
https://api.showly.aiすべてのリクエストには TLS が必要です。通常の HTTP リクエストは拒否されます。
バージョン管理
現在、/v1/ プレフィックスや Api-Version ヘッダーはありません。API は単一トラックで提供されます。破壊的変更は重要な変更として扱い、日付、対象ルート、移行手順とともに公開の変更履歴に記載します。連携機能を運用している場合は、そのページを確認してください。新しい任意フィールドやエンドポイントなどの後方互換な追加は、通常のリリースとして提供されます。
認証
すべてのリクエストには Authorization: Bearer <token> ヘッダーが必要です。使用する認証情報:
- パーソナル アクセス トークン (PAT) — プレフィックス
sk_live_/sk_test_。 PAT は、それが作成された単一のワークスペースにスコープされ、作成時に付与されたスコープを保持します。アドホック スクリプトや CI に便利です。 - MCP トークン — プレフィックス
mcp_live_/mcp_test_、ワークスペース設定 → MCP クライアント から発行されるか、デバイス フローによって作成されます。単一のワークスペースにスコープされ、MCP サーフェスによって使用されます。また、REST 通話も認証します。
静的トークンを設定できないエージェント環境では、Showly の RFC 8628 デバイス認可フロー（POST /oauth/device の後に POST /oauth/token をポーリング）を利用できます。このフローは、認可したユーザーに紐づく MCP トークンを発行します。詳しい手順とトークンのローテーションは認証を参照してください。
応答エンベロープ
すべての JSON 応答は同じエンベロープを使用します。成功した応答:
{
"ok": true,
"data": { ... }
}エラー:
{
"ok": false,
"error": { "code": "string", "message": "string" }
}error.code は安定したコントラクトです。error.message ではなく、そこに分岐します。コードはケバブまたはヘビのケースの識別子 (rate_limited、idempotency_key_conflict、not_found) です。メッセージは人間の読者を対象としており、リリースごとに変更される可能性があります。
レート制限
レート制限は、認証されたワークスペースのアクティブなレート制限から選択されます 構成。 MCP トークンは、保守的な 60 リクエスト/分の上限を使用します ワークスペースの請求に関係なく。ホット ルートには、ルートごとの上限をさらに厳しくすることができます。
レートが制限されている場合、サーバーは error.code: "rate_limited" とバックオフを数秒で運ぶ Retry-After ヘッダーを含む HTTP 429 を返します。 Retry-After を正規の待機として扱います。それより早く再試行しないでください。
べき等性
デプロイメントの作成 — POST /sites/:siteId/deploy — Idempotency-Key ヘッダーが必要です。これがないと、サーバーは 428 を返します。鍵はあなたの選択です。論理的な試行ごとに UUID を使用することをお勧めします。 (実稼働パブリッシュは、environment: "production" と sourceDeploymentId で同じルートを通過するため、同じ要件が適用されます。) 他のルートではヘッダーは必要ありません。
同じキーをリプレイすると、最初の呼び出しからキャッシュされた応答が返されます。リクエスト本文が同じキーで変更された場合、サーバーは 409 を idempotency_key_conflict で返します。
読み取り専用の GET リクエストは当然冪等であり、ヘッダーを無視します。
ページネーション
リスト エンドポイント (GET /sites、GET /deployments) は現在、ワークスペースの完全な結果セットをプレーン配列として返します。カーソルや limit パラメーターはまだありません。ページネーションが出荷されるとき、それは追加的 (不透明なカーソル) になり、変更ログで発表されます。