Documentation overview

PREVIEWSHIP / HTTP API

HTTP API reference

Create and manage previews from your server or CI. All examples use the same API key and base URL.

Send X-API-Key on every request. Store the key in a server-side secret store; never embed it in browser code or public artifacts. Create an API key in the console and set the PREVIEWSHIP_API_KEY environment variable before using the examples.

Keep the API key server-side. Resources are scoped to its account. If a POST times out, check deployment history before retrying to avoid duplicates.

Response examples show selected fields; limits, IDs and timestamps are illustrative.

IDs are integers. Times such as createdAt and updatedAt are ISO 8601 UTC strings; see each endpoint for fields that can be null or omitted, which are distinct. Domains and quotas in examples are illustrative. Pagination uses zero-based page and size normalized to 1–100. current indicates whether this record is the deployment referenced by the project’s latestDeploymentId, retained indicates artifact retention, canRollback indicates eligibility by status, provider and artifact, and proOnly indicates account entitlement; these booleans are independent and do not guarantee an operation will succeed.

Common errors include 401 INVALID_API_KEY, 403 ACCOUNT_BLOCKED, 404 for missing resources, 409 for conflicts, 410 for unavailable artifacts, 413 for oversized uploads and 402 for daily/monthly deployment quota. Application business errors contain error.code and error.message; error.details may be absent. Gateway and proxy errors may use another format.

error.code →
POST/v1/deployments

Create a deployment

Upload a browser-ready artifact and queue a deployment.

Request
multipart/form-data: projectName and zip are required; source, visibility and password are optional. zip accepts a static ZIP or one HTML, Markdown or PDF file. projectName may contain at most 100 Unicode code points. source is a reporting label: CONSOLE, CLI, MCP, EXTENSION, API or GUEST; omitted or invalid values default to API for API-key requests. It does not change authentication. When setting a password, it must be 6–100 characters after trimming; an existing project may retain its saved password.
Response
201: deploymentId, status, deploymentSource, visibility, createdAt. visibility is the current project mode; a requested change applies on successful activation.
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

source: CONSOLE, CLI, MCP, EXTENSION, API, GUEST

Optional request source is a reporting label, not an authentication control. Missing or unrecognized input defaults to API for API-key calls.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

Limits and behavior
A new project defaults to PUBLIC; an existing project retains its access if visibility is omitted. PASSWORD requires an eligible plan. Quotas and content checks apply; 201 is not completion.
Additional field details

The multipart projectName field must be present; when blank, the server attempts to derive it from the uploaded filename. HTTP 201 only queues the deployment. Returned visibility is the project’s current mode; a requested change applies after successful activation. A new password in a deployment upload is trimmed before storage.

Example

curl -X POST 'https://api.previewship.com/v1/deployments' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY" \
  -F 'projectName=my-project' \
  -F 'zip=@./site.zip'

Response

{
  "deploymentId": 42,
  "status": "QUEUED",
  "deploymentSource": "API",
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:00:00Z"
}
GET/v1/deployments/{id}

Get a deployment

Check deployment and preview availability.

Request
Path id is the deployment ID; no request body.
Response
200: deploymentId, projectId, status, previewUrl, urlStatus, failureCode, errorMessage, contentRisk and retry availability.
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Computed URL availability based on backend state, considered together with deployment status. READY does not guarantee password-free access or access for every visitor; access controls, network and hosting conditions still apply.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

Computed hosting status, included only when hosting status service is available.

contentRisk.status: PENDING, CHECKING, RETRYING, COMPLETED

contentRisk may be null; its status describes the check, not URL access.

contentRisk.decision: PASS, HOLD, UNKNOWN

contentRisk.decision is a review outcome, not a guarantee that the preview is available.

contentRisk.riskLevel: LOW, MEDIUM, HIGH, UNKNOWN

contentRisk risk category; UNKNOWN is not a safe verdict.

contentRisk.notificationStatus: PENDING, RETRYING, ACCEPTED, FAILED, SKIPPED_NO_RECIPIENT, SKIPPED, SUPERSEDED

Notification state; ACCEPTED means accepted by the mail service, not delivered. RUNNING is exposed as PENDING. The known values are not a closed list.

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

Only present for certain findings; current known scope strings are not a closed list. actual and maximum use the units shown.

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

Common asynchronous deployment failureCode values, not a closed list; inspect errorMessage and retry eligibility.

Limits and behavior
Only the key owner’s deployment is returned. Poll with a delay until terminal; use the URL only when READY and available.
Additional field details

status describes the deployment; urlStatus describes preview availability and can differ after restriction or expiry. contentRisk may be null; attempt, maxAttempts and nextRetryAt may be omitted. contentCheckRetryAvailable does not guarantee current access rights permit retry; null contentCheckRetryExpiresAt can mean an existing retry can be retrieved. contentCheckUploadQuotaRestored is a compensation-processing marker, not proof that the current period’s counter changed. hostingStatus, hostingUntil, paidThrough, autoRenews and restorable are conditional; hostingUntil and paidThrough can be null. contentRisk.findings is an array; reasonCode is an extensible string and limit may be omitted. verifiedSafeRecheck=true requires a completed PASS, a non-empty model version and a recorded model SAFE verdict with HIGH confidence; PASS alone does not establish this.

Example

curl 'https://api.previewship.com/v1/deployments/42' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "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

List deployments

Search the account’s deployment history.

Request
Optional query: page (default 0), size (default 20), status, q, days. status accepts ALL or one value: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED. q matches project names or preview URLs; days filters the last N days.
Response
200: content, page, size, totalElements, totalPages and statusCounts. statusCounts reflects q and days but ignores the status filter.
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Computed URL availability based on backend state, considered together with deployment status. READY does not guarantee password-free access or access for every visitor; access controls, network and hosting conditions still apply.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

Limits and behavior
page starts at 0; size is clamped to 1–100. days is capped at 365; non-positive days means no time filter. Invalid status returns 400.

Example

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'

Response

{
  "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

Retry content check

Retry a recoverable technical content-check failure without uploading again.

Request
Path id is the failed deployment ID; no request body.
Response
201: deploymentId, status, deploymentSource, visibility and createdAt for the retry deployment.
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

Limits and behavior
Check contentCheckRetryAvailable first. The retained artifact, project state and access eligibility must permit retry; a newer published version prevents a new retry. Repeated calls for the same failure return its existing retry.
Additional field details

For accounts subject to commercial limits, the first retry consumes daily and monthly deployment counts, but no upload bytes. Repeated requests for the same failure may return the existing child without consuming the count again.

Example

curl -X POST 'https://api.previewship.com/v1/deployments/42/retry-content-check' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "deploymentId": 43,
  "status": "QUEUED",
  "deploymentSource": "CONTENT_CHECK_RETRY",
  "visibility": "PUBLIC",
  "createdAt": "2026-11-13T10:05:00Z"
}
GET/v1/projects

List projects

List projects owned by the API key account.

Request
No query parameters or body.
Response
200: projects array with project IDs, names, latest status, preview URL and access information.
Field values
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Computed URL availability based on backend state, considered together with deployment status. READY does not guarantee password-free access or access for every visitor; access controls, network and hosting conditions still apply.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

projectStatus: ACTIVE, BLOCKED

Known project states; tolerate other historical or future values.

hostingState: HOSTED, ARCHIVED

The hosting state is separate from projectStatus and content restrictions.

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

Computed hosting status, included only when hosting status service is available.

Limits and behavior
Guest projects are excluded; results are restricted to the account.
Additional field details

latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl and previewExpiresAt can be null. hostingStatus, hostingUntil, paidThrough, autoRenews and restorable appear only when hosting status is available; hostingUntil and paidThrough can be null. When the latest record is absent, latestDeploymentStatus, latestDeploymentSource and previewUrl can fall back to a historical READY Vercel deployment; these display fields need not correspond to latestDeploymentId.

Example

curl 'https://api.previewship.com/v1/projects' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "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}

Get a project

Read the project and its latest deployment information.

Request
Path id is the project ID; no request body.
Response
200: id, name, latestDeploymentId, latestDeploymentStatus, previewUrl, projectVisibility, urlStatus and canRedeploy.
Field values
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Computed URL availability based on backend state, considered together with deployment status. READY does not guarantee password-free access or access for every visitor; access controls, network and hosting conditions still apply.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

projectStatus: ACTIVE, BLOCKED

Known project states; tolerate other historical or future values.

hostingState: HOSTED, ARCHIVED

The hosting state is separate from projectStatus and content restrictions.

hostingStatus: BLOCKED, ARCHIVED, RESTORING, SUBSCRIPTION_ACTIVE, GRACE, FREE_ACTIVE, EXPIRED, RESTORE_UNAVAILABLE

Computed hosting status, included only when hosting status service is available.

Limits and behavior
Only owned, non-guest projects are available; missing or unowned projects return 404.
Additional field details

latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl and previewExpiresAt can be null. hostingStatus, hostingUntil, paidThrough, autoRenews and restorable appear only when hosting status is available; hostingUntil and paidThrough can be null. When the latest record is absent, latestDeploymentStatus, latestDeploymentSource and previewUrl can fall back to a historical READY Vercel deployment; these display fields need not correspond to latestDeploymentId.

Example

curl 'https://api.previewship.com/v1/projects/7' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "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}

Delete a project

Permanently delete a project and its deployments.

Request
Path id is the project ID; no request body.
Response
204 with no response body.
Limits and behavior
Deletes the fixed URL, hosted project, associated deployments and Showcase entry. The HTTP API does not require a project-name confirmation; verify the target before calling.

Example

curl -i -X DELETE 'https://api.previewship.com/v1/projects/7' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

HTTP 204 No Content
POST/v1/projects/{id}/redeploy-latest

Redeploy latest

Queue a deployment using the latest retained artifact.

Request
Path id is the project ID; no request body.
Response
201: deploymentId, projectId, status, deploymentSource and createdAt.
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

Limits and behavior
Requires a retained self-hosted artifact and an eligible project. Normally the URL must have expired; internal accounts may also redeploy a READY version. Poll the new deployment.
Additional field details

For accounts subject to commercial limits, a new redeployment consumes daily and monthly deployment counts but no upload bytes; it is asynchronous.

Example

curl -X POST 'https://api.previewship.com/v1/projects/7/redeploy-latest' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "deploymentId": 43,
  "projectId": 7,
  "status": "QUEUED",
  "deploymentSource": "CONSOLE",
  "createdAt": "2026-11-13T10:05:00Z"
}
GET/v1/projects/{id}/access

Get project access

Read the access mode for a project.

Request
Path id is the project ID; no request body.
Response
200: projectId, visibility, passwordProtected and proOnly.
Field values
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

Limits and behavior
Only an owned project can be queried; the password itself is never returned.
Additional field details

proOnly indicates that the account lacks password-access entitlement; visibility and passwordProtected describe the project’s current access and password state.

Example

curl 'https://api.previewship.com/v1/projects/7/access' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "projectId": 7,
  "visibility": "PUBLIC",
  "passwordProtected": false,
  "proOnly": false
}
PATCH/v1/projects/{id}/access

Update project access

Set public or password access.

Request
Path id is the project ID. JSON: visibility is PUBLIC or PASSWORD; password is optional when a password already exists.
Response
200: projectId, visibility, passwordProtected and proOnly.
Field values
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

Limits and behavior
PASSWORD requires an eligible plan and a 6–100 character password when none exists. PUBLIC clears the saved password; omitting or blank visibility defaults to PUBLIC.
Additional field details

proOnly indicates that the account lacks password-access entitlement; visibility and passwordProtected describe the project’s current access and password state.

Omitted or blank visibility becomes PUBLIC and clears the stored password. Password length is checked after trimming, but PATCH stores the supplied value without trimming, unlike a deployment upload. Avoid leading or trailing spaces.

Example

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"}'

Response

{
  "projectId": 7,
  "visibility": "PUBLIC",
  "passwordProtected": false,
  "proOnly": false
}
GET/v1/projects/{id}/versions

List project versions

List deployment history and rollback eligibility.

Request
Path id is the project ID. Optional query: page (default 0), size (default 20).
Response
200: projectId, latestDeploymentId, limit, versions, page, size, totalElements and totalPages.
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

Limits and behavior
page starts at 0; size is clamped to 1–100. Visible history follows account limits; check each version’s retained and canRollback fields.

Example

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'

Response

{
  "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

Roll back a version

Queue a new deployment from a retained historical version.

Request
Path id is the project ID and deploymentId is the target version; no request body.
Response
200: rolledBack, status, deploymentSource, deploymentId and previewUrl (initially null).
Field values
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

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

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

Limits and behavior
Only READY or SUPERSEDED self-hosted versions with retained artifacts qualify. The fixed URL switches only after activation; poll the returned deploymentId. HTTP does not require a project-name confirmation.
Additional field details

Rollback creates a new asynchronous deployment without consuming daily or monthly deployment counts. rolledBack=true acknowledges creation, not activation; poll the returned deploymentId.

Example

curl -X POST 'https://api.previewship.com/v1/projects/7/versions/42/rollback' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "rolledBack": true,
  "status": "QUEUED",
  "deploymentSource": "ROLLBACK",
  "deploymentId": 43,
  "previewUrl": null
}
GET/v1/usage

Get usage

Read account limits and current usage.

Request
No query parameters or body.
Response
200: plan, subscriptionStatus, businessLimitsApplied, maxUploadMb, daily, monthly, monthlyUpload, concurrentBuilds and projects.
Field values
plan / subscriptionPlan: FREE, PRO_MONTHLY, PRO_YEARLY

plan is effective entitlement; subscriptionPlan is the subscribed plan and can remain Pro after entitlement ends.

subscriptionStatus: FREE, ACTIVE, PAST_DUE, CANCELED

Current subscription state; it is independent of deployment status.

Limits and behavior
Limits depend on account policy and may change; use the returned values rather than assuming a fixed quota.
Additional field details

HTTP 402 can indicate a daily or monthly deployment count limit or a monthly upload limit. Actual limits and whether commercial limits apply depend on account policy.

Example

curl 'https://api.previewship.com/v1/usage' \
  -H "X-API-Key: $PREVIEWSHIP_API_KEY"

Response

{
  "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
  }
}

Field values

status

Deployment lifecycle: READY means successfully activated, but may later become SUPERSEDED, EXPIRED or BLOCKED. Some BLOCKED deployments may recover after remediation. No state is promised to remain permanent; status alone does not guarantee URL access.

QUEUED
Waiting in the queue
BUILDING
Worker processing
READY
Deployment activated
SUPERSEDED
Superseded by a later deployment
FAILED
Deployment failed
EXPIRED
Preview expired
BLOCKED
Deployment blocked

urlStatus

Computed URL availability based on backend state, considered together with deployment status. READY does not guarantee password-free access or access for every visitor; access controls, network and hosting conditions still apply.

READY
Calculated as available by backend status
BLOCKED
Access is blocked or restricted
EXPIRED
Preview has expired
UNAVAILABLE
No currently available URL

visibility / projectVisibility

For deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.

PUBLIC
Public access
PASSWORD
Password-protected access
PRIVATE
Historical private mode; not accepted by these write APIs

source

Optional request source is a reporting label, not an authentication control. Missing or unrecognized input defaults to API for API-key calls.

CONSOLE
Console label
CLI
CLI label
MCP
MCP label
EXTENSION
Editor extension label
API
Direct API label
GUEST
Guest label

deploymentSource

Response source is a label, not a closed enum. Older or new values may occur. Most detail/list views map historical REDEPLOY to CONSOLE; version history can return the stored value.

CONSOLE
Console or normalized historical redeploy
CLI
CLI
MCP
MCP
EXTENSION
Editor extension
API
Direct API
GUEST
Guest
UNKNOWN
Source unknown
CONTENT_CHECK_RETRY
Technical check retry
ROLLBACK
Rollback deployment
SUBSCRIPTION_RESTORE
Subscription restoration
REDEPLOY
Historical stored redeploy source

projectStatus

Known project states; tolerate other historical or future values.

ACTIVE
Project active
BLOCKED
Project blocked

hostingState

The hosting state is separate from projectStatus and content restrictions.

HOSTED
Project hosted
ARCHIVED
Project archived

hostingStatus

Computed hosting status, included only when hosting status service is available.

BLOCKED
Project or deployment blocked
ARCHIVED
Project archived
RESTORING
Subscription restore in progress
SUBSCRIPTION_ACTIVE
Paid hosting active
GRACE
Paid hosting grace period
FREE_ACTIVE
Free hosting active
EXPIRED
Expired and restorable
RESTORE_UNAVAILABLE
Restore unavailable

plan / subscriptionPlan

plan is effective entitlement; subscriptionPlan is the subscribed plan and can remain Pro after entitlement ends.

FREE
Free plan
PRO_MONTHLY
Pro monthly plan
PRO_YEARLY
Pro yearly plan

subscriptionStatus

Current subscription state; it is independent of deployment status.

FREE
Free subscription state
ACTIVE
Active subscription
PAST_DUE
Payment past due
CANCELED
Subscription canceled

contentRisk.status

contentRisk may be null; its status describes the check, not URL access.

PENDING
Awaiting review
CHECKING
Review in progress
RETRYING
Scheduled to retry
COMPLETED
Check completed; decision can still be UNKNOWN

contentRisk.decision

contentRisk.decision is a review outcome, not a guarantee that the preview is available.

PASS
Check passed
HOLD
Risk held
UNKNOWN
No conclusive decision

contentRisk.riskLevel

contentRisk risk category; UNKNOWN is not a safe verdict.

LOW
Low risk
MEDIUM
Medium risk
HIGH
High risk
UNKNOWN
Risk undetermined

contentRisk.notificationStatus

Notification state; ACCEPTED means accepted by the mail service, not delivered. RUNNING is exposed as PENDING. The known values are not a closed list.

PENDING
Waiting to send
RETRYING
Send will be retried
ACCEPTED
Mail service accepted
FAILED
Sending failed
SKIPPED_NO_RECIPIENT
No recipient
SKIPPED
Notification skipped
SUPERSEDED
Notice superseded

contentRisk.findings[].limit.scope

Only present for certain findings; current known scope strings are not a closed list. actual and maximum use the units shown.

TOTAL_BYTES
Total artifact bytes
FILE_BYTES
File bytes
MARKUP_NODES
Markup nodes
LINKED_SCRIPT_BYTES
Linked script bytes
AI_TAG_CHARS_AT_LEAST
At least this many characters in an unfinished HTML start tag
AI_CONTEXT_CHARS
Check context characters
AI_CANDIDATES
Safety candidates
AI_BATCHES
AI review batches
AI_INPUT_CHARS
AI input characters

error.code

Common HTTP error.code values, not a closed list; inspect message and optional details.

INVALID_API_KEY
Missing or invalid key
ACCOUNT_BLOCKED
Account blocked
INVALID_PARAM
Invalid parameter
DAILY_QUOTA_EXCEEDED
Daily deploy quota exceeded
MONTHLY_QUOTA_EXCEEDED
Monthly deploy quota exceeded
MONTHLY_UPLOAD_EXCEEDED
Monthly upload quota exceeded
MAX_PROJECTS_EXCEEDED
Project quota exceeded
ZIP_TOO_LARGE
Upload too large
DEPLOYMENT_NOT_REDEPLOYABLE
Deployment cannot be retried
DEPLOYMENT_SUPERSEDED
A newer deployment supersedes this one
PROJECT_URL_NOT_EXPIRED
Project URL is not expired
PROJECT_ARCHIVED
Project archived
ARTIFACT_NOT_RETAINED
Artifact not retained
PROJECT_NOT_FOUND
Project not found or inaccessible
DEPLOYMENT_NOT_FOUND
Deployment not found or inaccessible
PROJECT_BLOCKED
Project blocked
DOWNGRADE_NOT_ALLOWED
Operation not allowed by current plan

failureCode

Common asynchronous deployment failureCode values, not a closed list; inspect errorMessage and retry eligibility.

UNBUILT_SOURCE
Source not built
EMPTY_ARCHIVE
Archive empty
MISSING_ENTRY_FILE
Entry file missing
MULTIPLE_BUILD_OUTPUTS
Multiple build outputs
INVALID_PDF_FILE
Invalid PDF
INVALID_ARCHIVE_PATH
Invalid archive path
ARCHIVE_READ_FAILED
Could not read archive
UPLOAD_ARTIFACT_MISSING
Uploaded artifact missing
DEPLOYMENT_PROVIDER_FAILED
Hosting provider failed
CONTENT_CHECK_UNAVAILABLE
Content check unavailable
CONTENT_RISK_HIGH
Content risk confirmed
MULTIPLE_PDF_FILES
Multiple PDF files
ZIP_TOO_LARGE
Archive too large
DEPLOYMENT_SUPERSEDED
Superseded by a newer deployment