每次請求以 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 →/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。
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 不能判定連結可存取。
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,COMPLETEDcontentRisk 可為 null;其 status 表示檢查進度,不代表連結可存取。
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"
}/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
}
}/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"
}/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 不保證無需密碼或每位訪客都能存取;仍受存取控制、網路和託管狀況影響。
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 不能判定連結可存取。
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLE依據後端狀態計算的連結可用性,須搭配部署狀態判斷。READY 不保證無需密碼或每位訪客都能存取;仍受存取控制、網路和託管狀況影響。
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,無回應本文。
- 使用限制與行為
- 固定連結、託管專案、關聯部署及 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 不能判定連結可存取。
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"
}/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 不能判定連結可存取。
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 不能判定連結可存取。
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
}/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 不能判定連結可存取。
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- 已被更新部署取代