每次请求通过 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- 历史私密模式,此写入接口不接受
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- 已被更新部署取代