サイト API

サイト サーフェスを使用すると、ワークスペース内でサイトを列挙、検査、作成できます。 REST API にはバージョン接頭辞がありません。以下のすべてのパスは https://api.showly.ai をルートとします。

サイトをリストする

GET /sites
Authorization: Bearer <token>

トークンが参照できるすべてのサイト (プレーンな配列 - まだページネーションはありません) と、ワークスペースのサイト キャップを持つ兄弟 entitlements オブジェクトを返します。

{
  "ok": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectId": "9b2f1c44-0d31-4c19-8a77-0f4bd4a1c001",
      "slug": "marketing-site",
      "name": "Marketing site",
      "framework": "next-export",
      "status": "active",
      "repositoryUrl": "https://github.com/acme/marketing",
      "productionUrl": "https://marketing-site.showly.site",
      "createdAt": "2026-03-01T10:14:22Z",
      "updatedAt": "2026-07-01T08:03:10Z"
    }
  ],
  "entitlements": {
    "maxSites": "unlimited",
    "currentSites": 3,
    "maxLiveSites": "unlimited",
    "currentLiveSites": 1
  }
}

サイト ID は UUID です。 framework 値は、ビルダーによって自動検出される自由形式の文字列です (例: next-export、astro、static-html)。

サイト数の枠

maxLiveSites は公開サイトの商用枠です。Free と Pro はどちらも "unlimited" です。個別契約や権限オーバーライドでは有限値が返る場合があり、 その場合だけ公開時に確認されます。

maxSites はプレビューのみのサイトを含む、すべての有効なサイトレコードを対象に します。すべての基本プランで "unlimited" です。有限値が現れるのは、運用者が ワークスペースに明示的なオーバーライドを設定した場合だけです。Free から Pro に 変更してもサイト枠は増えません。ワークスペースのプレビューに有効期限はありません。

単一のサイトを取得する

GET /sites/{siteId}

サイトと現在のマニフェストおよび最新の展開の概要を返します。

サイトを作成する

POST /sites
Content-Type: application/json

{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Docs",
  "slug": "docs",
  "repositoryUrl": "https://github.com/acme/docs"
}

201 と作成されたサイトを返します。projectId は、サイトが属するプロジェクトの UUID です。slug は ^[a-z0-9-]+$ に一致し、ワークスペース内で一意である必要があります。競合すると、409 と error.code: "slug_taken" が返されます。framework と repositoryUrl はオプションです。

ビルド構成は、作成本体ではなく、リポジトリにコミットされた showly.json マニフェスト内に存在します。ビルダーはフレームワークを自動検出し、そのファイルから rootDirectory、runtime、buildCommand、output、および関連フィールドを読み取ります。完全なスキーマについては、サイト マニフェストを参照してください。

ターゲットをデプロイする

デプロイターゲットはサイトごとではなく、組織レベルで構成されます。これらは /deployment-targets にマウントされます。

ターゲットには provider、mode、runtime が付いています。機能エンドポイントは 現在の環境で有効な組み合わせの信頼できる情報源。列挙型 API スキーマ内の値は、プロバイダーがプロビジョニングされることを保証するものではありません。 サポートされていない組み合わせは 400 deployment_target_not_implemented を返します。

自分のクラウド アカウントにデプロイメント ターゲットを登録するには、 byoCloudTargets 資格とユーザー アクター。トークンのみのボットは作成できません。 独自のクラウド ターゲットを更新または削除します。

Curl の例: エンドツーエンドの作成 + 最初のデプロイ

# 1. Create the site
SITE=$(curl -sS -X POST https://api.showly.ai/sites \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Demo", "slug": "demo", "repositoryUrl": "https://github.com/acme/demo" }' \
  | jq -r '.data.id')

# 2. Inspect the site (and the auto-detected manifest)
curl -sS "https://api.showly.ai/sites/$SITE" \
  -H "authorization: bearer $SHOWLY_TOKEN"

# 3. Request a preview deployment (siteId in the path; Idempotency-Key required)
curl -sS -X POST "https://api.showly.ai/sites/$SITE/deploy" \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{ "environment": "preview" }'

デプロイ作成の呼び出しは 202 を返します。POST /sites/:siteId/deploy には Idempotency-Key ヘッダーが必要です。ない場合は 428、競合する再試行には 409 を返します。デプロイの残りのライフサイクルはデプロイメントを参照してください。

アーカイブと復元

サイトを削除するとアーカイブされます。GET /sites からは消えますが、 GET /sites/archived には残ります。Preview のままという理由だけで自動的に アーカイブされることはありません。明示的に削除すると slug を再利用できます。 ワークスペースに有限の明示的な maxSites オーバーライドがある場合は、削除により そのオーバーライド枠も 1 つ解放されます。

1 つを以下のものと一緒に持ち帰ってください。

POST /sites/:siteId/restore

サイトは空に戻り、再デプロイの準備ができています。古いデプロイメントは存在しません。 ビルド アーティファクトがすでにガベージ コレクションされているため、復活しました。 復元にはサイト スロットが消費されるため、現在の状態の場合は 402 が返されます。 maxSites 手当、404 ID 不明の場合は別のもの ワークスペース、またはすでにアクティブです。

エラー