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 →/v1/deploymentsCreate 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,BLOCKEDDeployment 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,PRIVATEFor deployment or PATCH only PUBLIC and PASSWORD are accepted; PRIVATE may appear in historical reads.
source:CONSOLE,CLI,MCP,EXTENSION,API,GUESTOptional 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,REDEPLOYResponse 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"
}/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,BLOCKEDDeployment 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,UNAVAILABLEComputed 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,PRIVATEFor 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,REDEPLOYResponse 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_UNAVAILABLEComputed hosting status, included only when hosting status service is available.
contentRisk.status:PENDING,CHECKING,RETRYING,COMPLETEDcontentRisk may be null; its status describes the check, not URL access.
contentRisk.decision:PASS,HOLD,UNKNOWNcontentRisk.decision is a review outcome, not a guarantee that the preview is available.
contentRisk.riskLevel:LOW,MEDIUM,HIGH,UNKNOWNcontentRisk risk category; UNKNOWN is not a safe verdict.
contentRisk.notificationStatus:PENDING,RETRYING,ACCEPTED,FAILED,SKIPPED_NO_RECIPIENT,SKIPPED,SUPERSEDEDNotification 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_CHARSOnly 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_SUPERSEDEDCommon 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"
}/v1/deploymentsList 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,BLOCKEDDeployment 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,UNAVAILABLEComputed 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,REDEPLOYResponse 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
}
}/v1/deployments/{id}/retry-content-checkRetry 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,BLOCKEDDeployment 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,PRIVATEFor 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,REDEPLOYResponse 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"
}/v1/projectsList 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,BLOCKEDDeployment 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,UNAVAILABLEComputed 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,PRIVATEFor 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,REDEPLOYResponse 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.
hostingState:HOSTED,ARCHIVEDThe hosting state is separate from projectStatus and content restrictions.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEComputed 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"
}
]
}/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,BLOCKEDDeployment 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,UNAVAILABLEComputed 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,PRIVATEFor 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,REDEPLOYResponse 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.
hostingState:HOSTED,ARCHIVEDThe hosting state is separate from projectStatus and content restrictions.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEComputed 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"
}/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/v1/projects/{id}/redeploy-latestRedeploy 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,BLOCKEDDeployment 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,REDEPLOYResponse 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"
}/v1/projects/{id}/accessGet 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,PRIVATEFor 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
}/v1/projects/{id}/accessUpdate 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,PRIVATEFor 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
}/v1/projects/{id}/versionsList 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,BLOCKEDDeployment 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,REDEPLOYResponse 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
}/v1/projects/{id}/versions/{deploymentId}/rollbackRoll 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,BLOCKEDDeployment 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,REDEPLOYResponse 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
}/v1/usageGet 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_YEARLYplan is effective entitlement; subscriptionPlan is the subscribed plan and can remain Pro after entitlement ends.
subscriptionStatus:FREE,ACTIVE,PAST_DUE,CANCELEDCurrent 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