ドキュメント概要

PREVIEWSHIP / HTTP API

HTTP API リファレンス

サーバーや CI からプレビューを作成・管理します。例では同じ API Key とベース URL を使用します。

すべてのリクエストに X-API-Key を付けます。キーはサーバー側のシークレットに保管し、ブラウザーのコードや公開物に含めないでください。 例を使う前にコンソールで API Key を作成し、環境変数 PREVIEWSHIP_API_KEY を設定してください。

API Key はサーバー側に保管し、リソースは所有アカウント単位で隔離されます。POST がタイムアウトした場合は重複を避けるため、再試行前に履歴を確認してください。

レスポンス例は一部のフィールドのみを示し、上限・ID・日時は例です。

ID は整数です。createdAt、updatedAt などの時刻は ISO 8601 UTC 文字列です。フィールドの省略と null は異なり、詳細は各 API を参照してください。例のドメインや枠は説明用です。ページ番号 page は 0 から始まり、size はサーバーで 1–100 に正規化されます。current はこの記録がプロジェクトの latestDeploymentId が指すデプロイかどうか、retained は成果物の保持、canRollback は状態・提供方式・成果物による可否、proOnly はアカウント権限の制限を示す独立した真偽値で、操作の成功を保証しません。

主なエラーは 401 INVALID_API_KEY、403 ACCOUNT_BLOCKED、404 対象なし、409 状態競合、410 成果物利用不可、413 容量超過、日次・月次デプロイ枠超過時の 402 です。アプリケーションの業務エラーには error.code と error.message があり、error.details は省略される場合があります。ゲートウェイやプロキシのエラーは異なる形式の場合があります。

error.code →
POST/v1/deployments

デプロイを作成

ブラウザーで開ける成果物をアップロードし、デプロイをキューに入れます。

リクエスト
multipart/form-data:projectName と zip は必須、source、visibility、password は任意。zip は静的 ZIP または単一の HTML、Markdown、PDF。 projectName は Unicode コードポイントで最大 100 個です。 source は集計用の識別値で、CONSOLE、CLI、MCP、EXTENSION、API、GUEST を指定できます。API Key リクエストでは省略または無効なら API となり、認証には影響しません。新しいパスワードを設定する場合、前後の空白を除いて 6–100 文字です。既存プロジェクトでは保存済みパスワードを継続使用できます。
レスポンス
201:deploymentId、status、deploymentSource、visibility、createdAt。visibility は現在のアクセス設定で、要求した変更は有効化成功後に適用されます。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

source: CONSOLE, CLI, MCP, EXTENSION, API, GUEST

任意の source は記録用ラベルで、認証には影響しません。API Key リクエストで省略または無効の場合は API になります。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

制限と動作
visibility 省略時、新規は PUBLIC、既存は現在の設定を維持します。PASSWORD は対象プランが必要。利用枠と内容確認が適用され、201 は完了を意味しません。
フィールドと動作の詳細

multipart の projectName フィールドは必須です。空白の場合、サーバーはアップロードしたファイル名からの推定を試みます。HTTP 201 はキューへの登録のみを示します。返される visibility は現在の設定で、要求した変更は有効化成功後に適用されます。デプロイ時の新規パスワードは前後の空白を除いて保存されます。

使用例

curl -X POST 'https://api.previewship.com/v1/deployments' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" \
  -F 'projectName=my-project' \
  -F 'zip=@./site.zip'

レスポンス

{
  "deploymentId": 42,
  "status": "QUEUED",
  "deploymentSource": "API",
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:00:00Z"
}
GET/v1/deployments/{id}

デプロイを取得

デプロイ状態とプレビューの利用可否を確認します。

リクエスト
パスの id はデプロイ ID。本文は不要。
レスポンス
200:deploymentId、projectId、status、previewUrl、urlStatus、failureCode、errorMessage、contentRisk、再試行可否。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

バックエンド状態から算出した URL の可用性です。デプロイ状態と併せて確認してください。READY でもパスワード不要や全訪問者のアクセスは保証されず、アクセス制御、ネットワーク、ホスティング状況の影響を受けます。

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

算出されたホスティング状態。サービスが利用可能な場合のみ返されます。

contentRisk.status: PENDING, CHECKING, RETRYING, COMPLETED

contentRisk は null の場合があります。status はチェック進捗であり URL 可用性ではありません。

contentRisk.decision: PASS, HOLD, UNKNOWN

contentRisk.decision は審査結果であり、プレビューへのアクセスを保証しません。

contentRisk.riskLevel: LOW, MEDIUM, HIGH, UNKNOWN

contentRisk のリスク分類。UNKNOWN は安全を意味しません。

contentRisk.notificationStatus: PENDING, RETRYING, ACCEPTED, FAILED, SKIPPED_NO_RECIPIENT, SKIPPED, SUPERSEDED

通知状態。ACCEPTED はメールサービスの受理で、配信完了ではありません。RUNNING は PENDING として返されます。 既知の値であり固定一覧ではありません。

contentRisk.findings[].limit.scope: TOTAL_BYTES, FILE_BYTES, MARKUP_NODES, LINKED_SCRIPT_BYTES, AI_TAG_CHARS_AT_LEAST, AI_CONTEXT_CHARS, AI_CANDIDATES, AI_BATCHES, AI_INPUT_CHARS

一部 finding のみ存在するフィールドです。現在判明している scope は固定一覧ではありません。actual と maximum の単位は各値を参照。

failureCode: UNBUILT_SOURCE, EMPTY_ARCHIVE, MISSING_ENTRY_FILE, MULTIPLE_BUILD_OUTPUTS, INVALID_PDF_FILE, INVALID_ARCHIVE_PATH, ARCHIVE_READ_FAILED, UPLOAD_ARTIFACT_MISSING, DEPLOYMENT_PROVIDER_FAILED, CONTENT_CHECK_UNAVAILABLE, CONTENT_RISK_HIGH, MULTIPLE_PDF_FILES, ZIP_TOO_LARGE, DEPLOYMENT_SUPERSEDED

主な非同期デプロイ failureCode であり固定一覧ではありません。errorMessage と再試行可否を確認してください。

制限と動作
キーの所有アカウントのデプロイのみ対象。間隔を置いて終端状態まで確認し、READY かつ URL が利用可能な場合に使用します。
フィールドと動作の詳細

status はデプロイ状態、urlStatus はプレビューの利用可否です。隔離や期限切れ後は異なる場合があります。contentRisk は null になり得て、attempt、maxAttempts、nextRetryAt は省略され得ます。contentCheckRetryAvailable は現在の権限による再試行を保証しません。contentCheckRetryExpiresAt が null の場合、既存の再試行を取得できることがあります。contentCheckUploadQuotaRestored は補償処理の印であり、現在期間のカウンターが変化した証明ではありません。hostingStatus、hostingUntil、paidThrough、autoRenews、restorable は条件付きで返り、hostingUntil と paidThrough は null になり得ます。 contentRisk.findings は配列で、reasonCode は拡張可能な文字列、limit は省略され得ます。verifiedSafeRecheck=true は完了済み PASS、空でないモデルバージョン、記録されたモデル判定 SAFE と信頼度 HIGH を要求し、通常の PASS だけでは満たしません。

使用例

curl 'https://api.previewship.com/v1/deployments/42' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "deploymentId": 42,
  "projectId": 7,
  "projectName": "my-project",
  "status": "READY",
  "deploymentSource": "API",
  "previewUrl": "https://example.previewship.net",
  "urlStatus": "READY",
  "contentRestricted": false,
  "previewExpiresAt": null,
  "errorMessage": null,
  "failureCode": null,
  "contentRisk": null,
  "contentCheckArtifactExpiresAt": null,
  "contentCheckUploadQuotaRestored": false,
  "contentCheckRetryAvailable": false,
  "contentCheckRetryExpiresAt": null,
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:00:00Z",
  "updatedAt": "2026-11-13T10:01:00Z"
}
GET/v1/deployments

デプロイ一覧

アカウントのデプロイ履歴を検索します。

リクエスト
任意のクエリ:page(既定 0)、size(既定 20)、status、q、days。 status は ALL または QUEUED、BUILDING、READY、SUPERSEDED、FAILED、EXPIRED、BLOCKED のいずれか一つです。q はプロジェクト名またはプレビュー URL の部分一致、days は直近 N 日です。
レスポンス
200:content、page、size、totalElements、totalPages、statusCounts。 statusCounts は q と days の影響を受けますが、status フィルターの影響は受けません。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

バックエンド状態から算出した URL の可用性です。デプロイ状態と併せて確認してください。READY でもパスワード不要や全訪問者のアクセスは保証されず、アクセス制御、ネットワーク、ホスティング状況の影響を受けます。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

制限と動作
page は 0 始まり、size は 1–100 に制限。days は最大 365、0 以下は期間指定なし。不正な status は 400。

使用例

curl -G 'https://api.previewship.com/v1/deployments' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" \
  --data-urlencode 'page=0' --data-urlencode 'size=20' \
  --data-urlencode 'status=READY' --data-urlencode 'q=my-project' --data-urlencode 'days=30'

レスポンス

{
  "content": [
    {
      "deploymentId": 42,
      "projectId": 7,
      "projectName": "my-project",
      "status": "READY",
      "deploymentSource": "API",
      "previewUrl": "https://example.previewship.net",
      "urlStatus": "READY",
      "contentRestricted": false,
      "previewExpiresAt": null,
      "current": true,
      "canRollback": true,
      "createdAt": "2026-11-13T10:00:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "statusCounts": {
    "all": 1,
    "queued": 0,
    "building": 0,
    "ready": 1,
    "superseded": 0,
    "failed": 0,
    "expired": 0,
    "blocked": 0
  }
}
POST/v1/deployments/{id}/retry-content-check

内容確認を再試行

復旧可能な内容確認の技術的失敗を再アップロードせず再試行します。

リクエスト
パスの id は失敗したデプロイ ID。本文は不要。
レスポンス
201:再試行の deploymentId、status、deploymentSource、visibility、createdAt。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

制限と動作
先に contentCheckRetryAvailable を確認。保持成果物、プロジェクト状態とアクセス権が必要。新しい公開版がある場合は新規再試行不可。同じ失敗の再呼び出しは既存の再試行を返します。
フィールドと動作の詳細

商用枠が適用されるアカウントの初回再試行は日次・月次デプロイ回数を消費しますが、アップロード量は増えません。同じ失敗への再リクエストは既存の子デプロイを返し、回数を再消費しない場合があります。

使用例

curl -X POST 'https://api.previewship.com/v1/deployments/42/retry-content-check' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "deploymentId": 43,
  "status": "QUEUED",
  "deploymentSource": "CONTENT_CHECK_RETRY",
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:05:00Z"
}
GET/v1/projects

プロジェクト一覧

キー所有アカウントのプロジェクトを列挙します。

リクエスト
クエリと本文は不要。
レスポンス
200:projects 配列。ID、名前、最新状態、プレビュー URL、アクセス設定を含みます。
フィールド値
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

バックエンド状態から算出した URL の可用性です。デプロイ状態と併せて確認してください。READY でもパスワード不要や全訪問者のアクセスは保証されず、アクセス制御、ネットワーク、ホスティング状況の影響を受けます。

projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

latestDeploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

projectStatus: ACTIVE, BLOCKED

既知のプロジェクト状態です。未知の値にも対応してください。

hostingState: HOSTED, ARCHIVED

ホスティング状態は projectStatus やコンテンツ制限とは別です。

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

算出されたホスティング状態。サービスが利用可能な場合のみ返されます。

制限と動作
所有プロジェクトのみ。ゲストプロジェクトは含みません。
フィールドと動作の詳細

latestDeploymentId、latestDeploymentStatus、latestDeploymentSource、latestDeployedAt、previewUrl、previewExpiresAt は null になり得ます。hostingStatus、hostingUntil、paidThrough、autoRenews、restorable はホスティング状態が利用可能な場合のみ返り、hostingUntil と paidThrough は null になり得ます。 latest が指す記録がない場合、latestDeploymentStatus、latestDeploymentSource、previewUrl などは過去の READY Vercel デプロイにフォールバックすることがあり、latestDeploymentId と一致するとは限りません。

使用例

curl 'https://api.previewship.com/v1/projects' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "projects": [
    {
      "id": 7,
      "name": "my-project",
      "latestDeploymentId": 42,
      "latestDeploymentStatus": "READY",
      "latestDeploymentSource": "API",
      "latestDeployedAt": "2026-11-13T10:00:00Z",
      "deploymentCount": 1,
      "previewUrl": "https://example.previewship.net",
      "previewExpiresAt": null,
      "projectStatus": "ACTIVE",
      "contentRestricted": false,
      "hostingState": "HOSTED",
      "projectVisibility": "PUBLIC",
      "passwordProtected": false,
      "abuseBlockedAt": null,
      "abuseBlockedReason": null,
      "urlStatus": "READY",
      "canRedeploy": false,
      "createdAt": "2026-11-13T10:00:00Z",
      "updatedAt": "2026-11-13T10:01:00Z"
    }
  ]
}
GET/v1/projects/{id}

プロジェクトを取得

プロジェクトと最新デプロイの情報を取得します。

リクエスト
パスの id はプロジェクト ID。本文は不要。
レスポンス
200:id、name、latestDeploymentId、latestDeploymentStatus、previewUrl、projectVisibility、urlStatus、canRedeploy。
フィールド値
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

バックエンド状態から算出した URL の可用性です。デプロイ状態と併せて確認してください。READY でもパスワード不要や全訪問者のアクセスは保証されず、アクセス制御、ネットワーク、ホスティング状況の影響を受けます。

projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

latestDeploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

projectStatus: ACTIVE, BLOCKED

既知のプロジェクト状態です。未知の値にも対応してください。

hostingState: HOSTED, ARCHIVED

ホスティング状態は projectStatus やコンテンツ制限とは別です。

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

算出されたホスティング状態。サービスが利用可能な場合のみ返されます。

制限と動作
所有する非ゲストプロジェクトのみ対象。存在しないか所有外の場合は 404。
フィールドと動作の詳細

latestDeploymentId、latestDeploymentStatus、latestDeploymentSource、latestDeployedAt、previewUrl、previewExpiresAt は null になり得ます。hostingStatus、hostingUntil、paidThrough、autoRenews、restorable はホスティング状態が利用可能な場合のみ返り、hostingUntil と paidThrough は null になり得ます。 latest が指す記録がない場合、latestDeploymentStatus、latestDeploymentSource、previewUrl などは過去の READY Vercel デプロイにフォールバックすることがあり、latestDeploymentId と一致するとは限りません。

使用例

curl 'https://api.previewship.com/v1/projects/7' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "id": 7,
  "name": "my-project",
  "latestDeploymentId": 42,
  "latestDeploymentStatus": "READY",
  "latestDeploymentSource": "API",
  "latestDeployedAt": "2026-11-13T10:00:00Z",
  "deploymentCount": 1,
  "previewUrl": "https://example.previewship.net",
  "previewExpiresAt": null,
  "projectStatus": "ACTIVE",
  "contentRestricted": false,
  "hostingState": "HOSTED",
  "projectVisibility": "PUBLIC",
  "passwordProtected": false,
  "abuseBlockedAt": null,
  "abuseBlockedReason": null,
  "urlStatus": "READY",
  "canRedeploy": false,
  "createdAt": "2026-11-13T10:00:00Z",
  "updatedAt": "2026-11-13T10:01:00Z"
}
DELETE/v1/projects/{id}

プロジェクトを削除

プロジェクトと関連デプロイを永久削除します。

リクエスト
パスの id はプロジェクト ID。本文は不要。
レスポンス
204、本文なし。
制限と動作
固定 URL、ホスト済みプロジェクト、関連デプロイ、Showcase が削除されます。HTTP API はプロジェクト名による確認を要求しないため、対象を事前に確認してください。

使用例

curl -i -X DELETE 'https://api.previewship.com/v1/projects/7' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

HTTP 204 No Content
POST/v1/projects/{id}/redeploy-latest

最新バージョンを再デプロイ

保持された最新成果物からデプロイをキューに入れます。

リクエスト
パスの id はプロジェクト ID。本文は不要。
レスポンス
201:deploymentId、projectId、status、deploymentSource、createdAt。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

制限と動作
対象プロジェクトと保持されたセルフホスト成果物が必要。通常は URL の期限切れが条件で、内部アカウントは READY 版も再デプロイ可能。新しいデプロイをポーリングします。
フィールドと動作の詳細

商用枠が適用されるアカウントの再デプロイは日次・月次デプロイ回数を消費しますが、アップロード量は増えません。返されるデプロイは非同期です。

使用例

curl -X POST 'https://api.previewship.com/v1/projects/7/redeploy-latest' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "deploymentId": 43,
  "projectId": 7,
  "status": "QUEUED",
  "deploymentSource": "CONSOLE",
  "createdAt": "2026-11-13T10:05:00Z"
}
GET/v1/projects/{id}/access

アクセス設定を取得

プロジェクトのアクセス方式を取得します。

リクエスト
パスの id はプロジェクト ID。本文は不要。
レスポンス
200:projectId、visibility、passwordProtected、proOnly。
フィールド値
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

制限と動作
所有プロジェクトのみ対象。パスワード自体は返されません。
フィールドと動作の詳細

proOnly はアカウントにパスワードアクセス権限がないことを示します。プロジェクトの現在の方式とパスワード有無は visibility と passwordProtected を確認してください。

使用例

curl 'https://api.previewship.com/v1/projects/7/access' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "projectId": 7,
  "visibility": "PUBLIC",
  "passwordProtected": false,
  "proOnly": false
}
PATCH/v1/projects/{id}/access

アクセス設定を変更

公開またはパスワードアクセスを設定します。

リクエスト
パスの id はプロジェクト ID。JSON:visibility は PUBLIC または PASSWORD。既存パスワードがあれば password は省略可能。
レスポンス
200:projectId、visibility、passwordProtected、proOnly。
フィールド値
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

制限と動作
PASSWORD は対象プランが必要。パスワードが未設定なら 6–100 文字を指定。PUBLIC は保存済みパスワードを消去し、visibility の省略・空欄は PUBLIC になります。
フィールドと動作の詳細

proOnly はアカウントにパスワードアクセス権限がないことを示します。プロジェクトの現在の方式とパスワード有無は visibility と passwordProtected を確認してください。

visibility の省略または空白は PUBLIC となり、保存済みパスワードを消去します。長さは前後の空白を除いて検証しますが、PATCH は元の入力を保存します。デプロイ時と異なるため、パスワードの前後に空白を入れないことを推奨します。

使用例

curl -X PATCH 'https://api.previewship.com/v1/projects/7/access' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" -H 'Content-Type: application/json' \
  -d '{"visibility":"PUBLIC"}'

レスポンス

{
  "projectId": 7,
  "visibility": "PUBLIC",
  "passwordProtected": false,
  "proOnly": false
}
GET/v1/projects/{id}/versions

バージョン一覧

履歴とロールバック可否を取得します。

リクエスト
パスの id はプロジェクト ID。任意のクエリ page(既定 0)、size(既定 20)。
レスポンス
200:projectId、latestDeploymentId、limit、versions、page、size、totalElements、totalPages。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

制限と動作
page は 0 始まり、size は 1–100。表示履歴はアカウントの制限に従います。各版の retained と canRollback を確認してください。

使用例

curl -G 'https://api.previewship.com/v1/projects/7/versions' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" --data-urlencode 'page=0' --data-urlencode 'size=20'

レスポンス

{
  "projectId": 7,
  "latestDeploymentId": 42,
  "limit": 3,
  "versions": [
    {
      "deploymentId": 42,
      "current": true,
      "status": "READY",
      "deploymentSource": "API",
      "previewUrl": "https://example.previewship.net",
      "previewExpiresAt": null,
      "artifactExpiresAt": null,
      "artifactDeletedAt": null,
      "retained": true,
      "canRollback": true,
      "createdAt": "2026-11-13T10:00:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}
POST/v1/projects/{id}/versions/{deploymentId}/rollback

バージョンをロールバック

保持された過去版から新しい非同期デプロイを作成します。

リクエスト
パスの id はプロジェクト ID、deploymentId は対象版 ID。本文は不要。
レスポンス
200:rolledBack、status、deploymentSource、deploymentId、previewUrl(初期値 null)。
フィールド値
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

deploymentSource: CONSOLE, CLI, MCP, EXTENSION, API, GUEST, UNKNOWN, CONTENT_CHECK_RETRY, ROLLBACK, SUBSCRIPTION_RESTORE, REDEPLOY

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

制限と動作
保持成果物のあるセルフホストの READY または SUPERSEDED 版のみ対象。固定 URL は有効化成功後に切り替わるため、返された deploymentId を確認します。HTTP は名前確認を要求しません。
フィールドと動作の詳細

ロールバックは日次・月次デプロイ回数を消費せず、新しい非同期デプロイを作成します。rolledBack=true は作成の受付であり、有効化の完了ではありません。返された deploymentId を確認してください。

使用例

curl -X POST 'https://api.previewship.com/v1/projects/7/versions/42/rollback' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "rolledBack": true,
  "status": "QUEUED",
  "deploymentSource": "ROLLBACK",
  "deploymentId": 43,
  "previewUrl": null
}
GET/v1/usage

使用量を取得

アカウントの上限と現在の使用量を取得します。

リクエスト
クエリと本文は不要。
レスポンス
200:plan、subscriptionStatus、businessLimitsApplied、maxUploadMb、daily、monthly、monthlyUpload、concurrentBuilds、projects。
フィールド値
plan / subscriptionPlan: FREE, PRO_MONTHLY, PRO_YEARLY

plan は現在有効な権益、subscriptionPlan は実際の購読プランです。権益終了後も後者は Pro の場合があります。

subscriptionStatus: FREE, ACTIVE, PAST_DUE, CANCELED

現在のサブスクリプション状態で、デプロイ状態とは別です。

制限と動作
制限はアカウントのポリシーによって変わるため、返された値を確認してください。
フィールドと動作の詳細

HTTP 402 は日次・月次デプロイ回数または月間アップロード量の上限を示す場合があります。実際の上限と商用枠の適用はアカウントのポリシーによって決まります。

使用例

curl 'https://api.previewship.com/v1/usage' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

レスポンス

{
  "plan": "FREE",
  "subscriptionPlan": "FREE",
  "subscriptionStatus": "FREE",
  "paidThrough": null,
  "autoRenews": false,
  "businessLimitsApplied": true,
  "maxUploadMb": 15,
  "daily": {
    "used": 1,
    "limit": 5,
    "resetAt": "2026-11-14T00:00:00Z"
  },
  "monthly": {
    "used": 1,
    "limit": 20,
    "resetAt": "2026-12-01T00:00:00Z"
  },
  "monthlyUpload": {
    "usedMb": 1,
    "limitMb": 200,
    "resetAt": "2026-12-01T00:00:00Z"
  },
  "concurrentBuilds": {
    "current": 0,
    "limit": 1
  },
  "projects": {
    "used": 1,
    "limit": 1
  }
}

フィールド値

status

デプロイの状態です。READY は有効化成功を示しますが、その後 SUPERSEDED、EXPIRED、BLOCKED に変わる場合があります。一部の BLOCKED は修正後に回復する場合があります。いずれの状態も永続するとは限らず、status だけでは URL の利用可否は判断できません。

QUEUED
キューで待機中
BUILDING
ワーカーが処理中
READY
デプロイが有効化された
SUPERSEDED
後のデプロイに置き換えられた
FAILED
デプロイ失敗
EXPIRED
プレビュー期限切れ
BLOCKED
デプロイがブロックされた

urlStatus

バックエンド状態から算出した URL の可用性です。デプロイ状態と併せて確認してください。READY でもパスワード不要や全訪問者のアクセスは保証されず、アクセス制御、ネットワーク、ホスティング状況の影響を受けます。

READY
バックエンド状態から利用可能と算出
BLOCKED
アクセスがブロックまたは制限されている
EXPIRED
プレビュー期限切れ
UNAVAILABLE
現在利用可能な URL がない

visibility / projectVisibility

デプロイと PATCH の書き込みは PUBLIC と PASSWORD のみ。過去の読み取りでは PRIVATE が返る場合があります。

PUBLIC
公開アクセス
PASSWORD
パスワードアクセス
PRIVATE
過去の非公開モード。書き込み API では指定不可

source

任意の source は記録用ラベルで、認証には影響しません。API Key リクエストで省略または無効の場合は API になります。

CONSOLE
コンソールのラベル
CLI
CLI のラベル
MCP
MCP のラベル
EXTENSION
エディタ拡張のラベル
API
直接 API のラベル
GUEST
ゲストのラベル

deploymentSource

レスポンスのソースは固定列挙ではなく、過去や将来の値もあり得ます。多くの詳細・一覧では旧 REDEPLOY を CONSOLE に変換しますが、バージョン一覧は保存値を返す場合があります。

CONSOLE
コンソールまたは正規化された旧再デプロイ
CLI
CLI
MCP
MCP
EXTENSION
エディタ拡張
API
直接 API
GUEST
ゲスト
UNKNOWN
ソース不明
CONTENT_CHECK_RETRY
技術的チェックの再試行
ROLLBACK
ロールバックデプロイ
SUBSCRIPTION_RESTORE
サブスクリプション復元
REDEPLOY
保存された旧再デプロイソース

projectStatus

既知のプロジェクト状態です。未知の値にも対応してください。

ACTIVE
プロジェクト有効
BLOCKED
プロジェクトがブロックされた

hostingState

ホスティング状態は projectStatus やコンテンツ制限とは別です。

HOSTED
ホスティング中
ARCHIVED
アーカイブ済み

hostingStatus

算出されたホスティング状態。サービスが利用可能な場合のみ返されます。

BLOCKED
プロジェクトまたはデプロイがブロックされた
ARCHIVED
アーカイブ済み
RESTORING
サブスクリプション復元中
SUBSCRIPTION_ACTIVE
有料ホスティング有効
GRACE
有料ホスティングの猶予期間
FREE_ACTIVE
無料ホスティング有効
EXPIRED
期限切れで復元可能
RESTORE_UNAVAILABLE
復元不可

plan / subscriptionPlan

plan は現在有効な権益、subscriptionPlan は実際の購読プランです。権益終了後も後者は Pro の場合があります。

FREE
無料プラン
PRO_MONTHLY
Pro 月額プラン
PRO_YEARLY
Pro 年額プラン

subscriptionStatus

現在のサブスクリプション状態で、デプロイ状態とは別です。

FREE
無料の購読状態
ACTIVE
購読有効
PAST_DUE
支払い期限超過
CANCELED
購読キャンセル済み

contentRisk.status

contentRisk は null の場合があります。status はチェック進捗であり URL 可用性ではありません。

PENDING
審査待ち
CHECKING
審査中
RETRYING
再試行待ち
COMPLETED
チェック完了。ただし結果は UNKNOWN の場合がある

contentRisk.decision

contentRisk.decision は審査結果であり、プレビューへのアクセスを保証しません。

PASS
チェック通過
HOLD
リスクにより保留
UNKNOWN
判定未確定

contentRisk.riskLevel

contentRisk のリスク分類。UNKNOWN は安全を意味しません。

LOW
低リスク
MEDIUM
中リスク
HIGH
高リスク
UNKNOWN
リスク未確定

contentRisk.notificationStatus

通知状態。ACCEPTED はメールサービスの受理で、配信完了ではありません。RUNNING は PENDING として返されます。 既知の値であり固定一覧ではありません。

PENDING
送信待ち
RETRYING
送信再試行待ち
ACCEPTED
メールサービスが受理
FAILED
送信失敗
SKIPPED_NO_RECIPIENT
宛先なし
SKIPPED
通知をスキップ
SUPERSEDED
後続状態により通知が無効化

contentRisk.findings[].limit.scope

一部 finding のみ存在するフィールドです。現在判明している scope は固定一覧ではありません。actual と maximum の単位は各値を参照。

TOTAL_BYTES
成果物の総バイト数
FILE_BYTES
ファイルのバイト数
MARKUP_NODES
マークアップノード数
LINKED_SCRIPT_BYTES
参照スクリプトのバイト数
AI_TAG_CHARS_AT_LEAST
未完了 HTML 開始タグの最低文字数
AI_CONTEXT_CHARS
チェック文脈の文字数
AI_CANDIDATES
安全性候補数
AI_BATCHES
AI 審査バッチ数
AI_INPUT_CHARS
AI 入力文字数

error.code

主な HTTP error.code であり固定一覧ではありません。message と任意の details を確認してください。

INVALID_API_KEY
キー欠落または無効
ACCOUNT_BLOCKED
アカウントブロック
INVALID_PARAM
パラメータ無効
DAILY_QUOTA_EXCEEDED
日次デプロイ上限超過
MONTHLY_QUOTA_EXCEEDED
月次デプロイ上限超過
MONTHLY_UPLOAD_EXCEEDED
月次アップロード上限超過
MAX_PROJECTS_EXCEEDED
プロジェクト上限超過
ZIP_TOO_LARGE
アップロードが大きすぎる
DEPLOYMENT_NOT_REDEPLOYABLE
デプロイを直接再試行できない
DEPLOYMENT_SUPERSEDED
新しいデプロイが存在
PROJECT_URL_NOT_EXPIRED
プロジェクト URL は未失効
PROJECT_ARCHIVED
プロジェクトがアーカイブ済み
ARTIFACT_NOT_RETAINED
成果物が保持されていない
PROJECT_NOT_FOUND
プロジェクトが存在しないかアクセス不可
DEPLOYMENT_NOT_FOUND
デプロイが存在しないかアクセス不可
PROJECT_BLOCKED
プロジェクトがブロックされた
DOWNGRADE_NOT_ALLOWED
現在のプランでは操作不可

failureCode

主な非同期デプロイ failureCode であり固定一覧ではありません。errorMessage と再試行可否を確認してください。

UNBUILT_SOURCE
ソース未ビルド
EMPTY_ARCHIVE
アーカイブが空
MISSING_ENTRY_FILE
入口ファイルなし
MULTIPLE_BUILD_OUTPUTS
複数のビルド出力
INVALID_PDF_FILE
PDF 無効
INVALID_ARCHIVE_PATH
アーカイブパス無効
ARCHIVE_READ_FAILED
アーカイブ読み取り失敗
UPLOAD_ARTIFACT_MISSING
アップロード成果物なし
DEPLOYMENT_PROVIDER_FAILED
ホスティングプロバイダー障害
CONTENT_CHECK_UNAVAILABLE
コンテンツチェック利用不可
CONTENT_RISK_HIGH
コンテンツリスク確認
MULTIPLE_PDF_FILES
PDF ファイルが複数ある
ZIP_TOO_LARGE
アーカイブが大きすぎる
DEPLOYMENT_SUPERSEDED
新しいデプロイに置き換えられた