すべてのリクエストに 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 →/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"
}/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,COMPLETEDcontentRisk は null の場合があります。status はチェック進捗であり URL 可用性ではありません。
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"
}/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
}
}/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"
}/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 に変換しますが、バージョン一覧は保存値を返す場合があります。
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"
}
]
}/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 に変換しますが、バージョン一覧は保存値を返す場合があります。
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"
}/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/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"
}/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
}/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
}/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
}/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
}/v1/usage使用量を取得
アカウントの上限と現在の使用量を取得します。
- リクエスト
- クエリと本文は不要。
- レスポンス
- 200:plan、subscriptionStatus、businessLimitsApplied、maxUploadMb、daily、monthly、monthlyUpload、concurrentBuilds、projects。
- フィールド値
- plan / subscriptionPlan:
FREE,PRO_MONTHLY,PRO_YEARLYplan は現在有効な権益、subscriptionPlan は実際の購読プランです。権益終了後も後者は Pro の場合があります。
- 制限と動作
- 制限はアカウントのポリシーによって変わるため、返された値を確認してください。
- フィールドと動作の詳細
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- 新しいデプロイに置き換えられた