文档总览

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
历史私密模式,此写入接口不接受

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
已被更新部署取代