文件總覽

PREVIEWSHIP / HTTP API

HTTP API 介面參考

在伺服器或 CI 中建立與管理預覽。所有範例使用相同的 API Key 與基礎網址。

每次請求以 X-API-Key 傳遞金鑰。請將金鑰保存在伺服器端密鑰儲存區,不要寫入瀏覽器程式碼或公開產物。 使用範例前,請先在控制台建立 API Key,並設定 PREVIEWSHIP_API_KEY 環境變數。

API Key 僅保存在伺服器端;資源依金鑰所屬帳號隔離。POST 逾時後先查詢部署紀錄,以免重複建立。

回應範例僅顯示部分欄位;額度、ID 與時間均為範例。

ID 為整數。createdAt、updatedAt 等時間為 ISO 8601 UTC 字串;欄位不回傳與回傳 null 不相同,具體以各介面說明為準。範例網域和額度僅供示意。分頁 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 最多包含 100 個 Unicode 碼點。 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 不能判定連結可存取。

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 不能判定連結可存取。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

依據後端狀態計算的連結可用性,須搭配部署狀態判斷。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 表示檢查進度,不代表連結可存取。

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 且連結可用時使用連結。
欄位與使用細節

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 不能判定連結可存取。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

依據後端狀態計算的連結可用性,須搭配部署狀態判斷。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,非正數表示不按時間篩選;無效 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 不能判定連結可存取。

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

查詢專案列表

列出 API Key 所屬帳號的專案。

請求參數
不需查詢參數或請求本文。
回應
200:projects 陣列,包含專案 ID、名稱、最新部署狀態、預覽連結及存取方式。
欄位值
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

部署生命週期:READY 表示已成功啟用,之後仍可能變為 SUPERSEDED、EXPIRED 或 BLOCKED。部分 BLOCKED 部署在改善後可能恢復;不保證任何狀態永久不變,僅憑 status 不能判定連結可存取。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

依據後端狀態計算的連結可用性,須搭配部署狀態判斷。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 不能判定連結可存取。

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

依據後端狀態計算的連結可用性,須搭配部署狀態判斷。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,無回應本文。
使用限制與行為
固定連結、託管專案、關聯部署及 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 不能判定連結可存取。

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

回應來源不是封閉列舉,歷史或未來可能有其他值。多數詳情/列表將歷史 REDEPLOY 顯示為 CONSOLE,版本列表可能返回原值。

使用限制與行為
需要可用的自託管保留產物及符合條件的專案;通常要求連結已過期,內部帳號也可重新部署 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 不能判定連結可存取。

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 不能判定連結可存取。

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

回應來源不是封閉列舉,歷史或未來可能有其他值。多數詳情/列表將歷史 REDEPLOY 顯示為 CONSOLE,版本列表可能返回原值。

使用限制與行為
僅支援有保留產物的自託管 READY 或 SUPERSEDED 版本;成功啟用後才切換固定連結,應輪詢返回的 deploymentId。HTTP API 不要求傳專案名稱確認。
欄位與使用細節

回滾建立新的非同步部署,不消耗日、月部署次數。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 不能判定連結可存取。

QUEUED
等待佇列處理
BUILDING
工作器處理中
READY
部署已啟用
SUPERSEDED
已被後續部署取代
FAILED
部署失敗
EXPIRED
預覽已過期
BLOCKED
部署被阻擋

urlStatus

依據後端狀態計算的連結可用性,須搭配部署狀態判斷。READY 不保證無需密碼或每位訪客都能存取;仍受存取控制、網路和託管狀況影響。

READY
後端狀態計算為可用
BLOCKED
存取被封鎖或限制
EXPIRED
預覽已過期
UNAVAILABLE
目前沒有可用連結

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 表示檢查進度,不代表連結可存取。

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
專案連結尚未過期
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
已被更新部署取代