Resumen de documentación

PREVIEWSHIP / HTTP API

Referencia de la HTTP API

Crea y administra vistas previas desde tu servidor o CI. Todos los ejemplos usan la misma API key y URL base.

Envía X-API-Key en cada petición. Guarda la clave en un almacén de secretos del servidor, nunca en código del navegador ni archivos públicos. Antes de usar los ejemplos, crea una API key en la consola y configura la variable de entorno PREVIEWSHIP_API_KEY.

Guarda la API key en el servidor; los recursos se limitan a su cuenta. Si un POST agota el tiempo, consulta el historial antes de reintentar para evitar duplicados.

Los ejemplos de respuesta muestran algunos campos; límites, ID y fechas son ilustrativos.

Los ID son enteros. Fechas como createdAt y updatedAt son cadenas ISO 8601 UTC. La omisión de un campo y null son distintos; consulta cada interfaz. Los dominios y cuotas son ejemplos. La paginación usa page desde 0 y el servidor ajusta size a 1–100. current indica si este registro es el despliegue al que apunta latestDeploymentId del proyecto, retained indica conservación del artefacto, canRollback evalúa estado, proveedor y artefacto, y proOnly la limitación de derechos de la cuenta. Son booleanos independientes y no garantizan que la operación tenga éxito.

Errores habituales: 401 INVALID_API_KEY, 403 ACCOUNT_BLOCKED, 404 recurso no encontrado, 409 conflicto, 410 artefacto no disponible, 413 archivo demasiado grande y 402 al agotar la cuota diaria o mensual de despliegues. Los errores de negocio de la aplicación incluyen error.code y error.message; error.details puede omitirse. Los errores de la puerta de enlace o del proxy pueden tener otro formato.

error.code →
POST/v1/deployments

Crear un despliegue

Sube un artefacto listo para navegador y encola un despliegue.

Solicitud
multipart/form-data: projectName y zip son obligatorios; source, visibility y password son opcionales. zip acepta un ZIP estático o un archivo HTML, Markdown o PDF. projectName admite hasta 100 puntos de código Unicode. source solo identifica el origen: CONSOLE, CLI, MCP, EXTENSION, API o GUEST; si se omite o no es válido, una petición con API Key se clasifica como API. No cambia la autenticación. Al establecer una contraseña nueva, debe tener 6–100 caracteres tras quitar espacios al inicio y al final; un proyecto existente puede conservar la contraseña guardada.
Respuesta
201: deploymentId, status, deploymentSource, visibility, createdAt. visibility es el acceso actual; el cambio solicitado se aplica al activarse correctamente.
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

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

El source opcional es una etiqueta de origen, no controla la autenticación. Si falta o no es válido en una petición con API key, se usa API.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

Límites y comportamiento
Sin visibility, un proyecto nuevo es PUBLIC y uno existente conserva su acceso. PASSWORD requiere un plan apto. Se aplican cuotas y controles; 201 no significa que haya terminado.
Detalles de campos y comportamiento

El campo multipart projectName debe estar presente; si está vacío, el servidor intenta deducirlo del nombre del archivo. HTTP 201 solo indica que la tarea está en cola. La visibility devuelta es el acceso actual; el cambio solicitado se aplica tras la activación. Al subir un despliegue, una contraseña nueva se guarda sin espacios en los extremos.

Ejemplo

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

Respuesta

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

Consultar un despliegue

Consulta el estado y la disponibilidad de la vista previa.

Solicitud
El id de la ruta es el ID del despliegue; sin cuerpo.
Respuesta
200: deploymentId, projectId, status, previewUrl, urlStatus, failureCode, errorMessage, contentRisk y disponibilidad de reintento.
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidad de URL calculada según el estado del backend; compruébala junto con el estado del despliegue. READY no garantiza acceso sin contraseña ni para todos los visitantes: siguen influyendo los controles de acceso, la red y el alojamiento.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

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

Estado de alojamiento calculado; solo aparece cuando está disponible el servicio correspondiente.

contentRisk.status: PENDING, CHECKING, RETRYING, COMPLETED

contentRisk puede ser null; su status describe la comprobación, no el acceso a la URL.

contentRisk.decision: PASS, HOLD, UNKNOWN

contentRisk.decision es el resultado de la revisión y no garantiza acceso a la vista previa.

contentRisk.riskLevel: LOW, MEDIUM, HIGH, UNKNOWN

Categoría de riesgo de contentRisk; UNKNOWN no significa seguro.

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

Estado de notificación; ACCEPTED indica aceptación por el servicio de correo, no entrega. RUNNING se muestra como PENDING. Los valores conocidos no forman una lista cerrada.

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

Solo aparece en ciertos findings; los valores scope conocidos no son una lista cerrada. Las unidades de actual y maximum se indican abajo.

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

Valores failureCode habituales del despliegue asíncrono, no exhaustivos; consulta errorMessage y la disponibilidad de reintento.

Límites y comportamiento
Solo se devuelven despliegues de la cuenta dueña. Consulta con intervalos hasta el estado final y usa el enlace cuando esté READY y disponible.
Detalles de campos y comportamiento

status indica el estado del despliegue y urlStatus la disponibilidad de la vista previa; pueden diferir tras una restricción o caducidad. contentRisk puede ser null; attempt, maxAttempts y nextRetryAt pueden omitirse. contentCheckRetryAvailable no garantiza que los derechos actuales permitan reintentar; contentCheckRetryExpiresAt null puede indicar que se puede recuperar un reintento existente. contentCheckUploadQuotaRestored marca el procesamiento de la compensación, no prueba que cambiara el contador del período actual. hostingStatus, hostingUntil, paidThrough, autoRenews y restorable son condicionales; hostingUntil y paidThrough pueden ser null. contentRisk.findings es un array; reasonCode es una cadena extensible y limit puede omitirse. verifiedSafeRecheck=true requiere un PASS completado, una versión de modelo no vacía y un veredicto SAFE del modelo con confianza HIGH registrado; un PASS por sí solo no cumple esa condición.

Ejemplo

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

Respuesta

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

Listar despliegues

Busca en el historial de despliegues de la cuenta.

Solicitud
Consultas opcionales: page (0 por defecto), size (20 por defecto), status, q, days. status acepta ALL o un solo valor: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED o BLOCKED. q busca coincidencias parciales en el nombre del proyecto o la URL de preview; days filtra los últimos N días.
Respuesta
200: content, page, size, totalElements, totalPages y statusCounts. statusCounts aplica q y days, pero no el filtro status.
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidad de URL calculada según el estado del backend; compruébala junto con el estado del despliegue. READY no garantiza acceso sin contraseña ni para todos los visitantes: siguen influyendo los controles de acceso, la red y el alojamiento.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

Límites y comportamiento
page empieza en 0; size se limita a 1–100. days tiene máximo 365; valores no positivos no filtran por fecha. Un status inválido devuelve 400.

Ejemplo

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'

Respuesta

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

Reintentar comprobación

Reintenta un fallo técnico recuperable de la comprobación de contenido sin subir de nuevo.

Solicitud
El id de la ruta es el ID del despliegue fallido; sin cuerpo.
Respuesta
201: deploymentId, status, deploymentSource, visibility y createdAt del reintento.
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

Límites y comportamiento
Comprueba contentCheckRetryAvailable. Se requiere artefacto retenido, proyecto y acceso aptos; una versión publicada posterior impide crear otro reintento. Repetir la llamada devuelve el reintento existente.
Detalles de campos y comportamiento

En cuentas sujetas a límites comerciales, el primer reintento consume los cupos diario y mensual de despliegues sin añadir volumen de subida. Una petición repetida para el mismo fallo puede devolver el despliegue hijo existente sin descontar otra vez.

Ejemplo

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

Respuesta

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

Listar proyectos

Lista proyectos de la cuenta dueña de la API key.

Solicitud
Sin parámetros ni cuerpo.
Respuesta
200: array projects con ID, nombre, estado reciente, URL de preview y acceso.
Valores de campos
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidad de URL calculada según el estado del backend; compruébala junto con el estado del despliegue. READY no garantiza acceso sin contraseña ni para todos los visitantes: siguen influyendo los controles de acceso, la red y el alojamiento.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

projectStatus: ACTIVE, BLOCKED

Estados conocidos del proyecto; admite otros valores históricos o futuros.

hostingState: HOSTED, ARCHIVED

El estado de alojamiento es independiente de projectStatus y de las restricciones de contenido.

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

Estado de alojamiento calculado; solo aparece cuando está disponible el servicio correspondiente.

Límites y comportamiento
Solo proyectos de la cuenta; se excluyen proyectos de invitado.
Detalles de campos y comportamiento

latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl y previewExpiresAt pueden ser null. hostingStatus, hostingUntil, paidThrough, autoRenews y restorable solo aparecen si el estado de alojamiento está disponible; hostingUntil y paidThrough pueden ser null. Si falta el registro al que apunta latest, los valores mostrados como latestDeploymentStatus, latestDeploymentSource y previewUrl pueden proceder de un despliegue Vercel READY anterior y no corresponder a latestDeploymentId.

Ejemplo

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

Respuesta

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

Consultar un proyecto

Obtén datos del proyecto y su último despliegue.

Solicitud
El id de la ruta es el ID del proyecto; sin cuerpo.
Respuesta
200: id, name, latestDeploymentId, latestDeploymentStatus, previewUrl, projectVisibility, urlStatus y canRedeploy.
Valores de campos
latestDeploymentStatus: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

Disponibilidad de URL calculada según el estado del backend; compruébala junto con el estado del despliegue. READY no garantiza acceso sin contraseña ni para todos los visitantes: siguen influyendo los controles de acceso, la red y el alojamiento.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

projectStatus: ACTIVE, BLOCKED

Estados conocidos del proyecto; admite otros valores históricos o futuros.

hostingState: HOSTED, ARCHIVED

El estado de alojamiento es independiente de projectStatus y de las restricciones de contenido.

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

Estado de alojamiento calculado; solo aparece cuando está disponible el servicio correspondiente.

Límites y comportamiento
Solo proyectos propios no invitados; inexistentes o ajenos devuelven 404.
Detalles de campos y comportamiento

latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl y previewExpiresAt pueden ser null. hostingStatus, hostingUntil, paidThrough, autoRenews y restorable solo aparecen si el estado de alojamiento está disponible; hostingUntil y paidThrough pueden ser null. Si falta el registro al que apunta latest, los valores mostrados como latestDeploymentStatus, latestDeploymentSource y previewUrl pueden proceder de un despliegue Vercel READY anterior y no corresponder a latestDeploymentId.

Ejemplo

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

Respuesta

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

Eliminar un proyecto

Elimina permanentemente el proyecto y sus despliegues.

Solicitud
El id de la ruta es el ID del proyecto; sin cuerpo.
Respuesta
204 sin cuerpo.
Límites y comportamiento
Elimina la URL fija, alojamiento, despliegues asociados y Showcase. La HTTP API no pide confirmación del nombre: verifica el destino antes de llamar.

Ejemplo

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

Respuesta

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

Volver a desplegar el último

Encola un despliegue con el último artefacto retenido.

Solicitud
El id de la ruta es el ID del proyecto; sin cuerpo.
Respuesta
201: deploymentId, projectId, status, deploymentSource y createdAt.
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

Límites y comportamiento
Requiere proyecto apto y artefacto retenido autoalojado. Normalmente la URL debe estar caducada; cuentas internas también pueden redesplegar una versión READY. Consulta el nuevo despliegue.
Detalles de campos y comportamiento

En cuentas sujetas a límites comerciales, un redespliegue consume los cupos diario y mensual de despliegues sin añadir volumen de subida. Es asíncrono.

Ejemplo

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

Respuesta

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

Consultar acceso

Consulta el modo de acceso de un proyecto.

Solicitud
El id de la ruta es el ID del proyecto; sin cuerpo.
Respuesta
200: projectId, visibility, passwordProtected y proOnly.
Valores de campos
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

Límites y comportamiento
Solo proyectos propios; nunca devuelve la contraseña.
Detalles de campos y comportamiento

proOnly indica que la cuenta carece del derecho de acceso con contraseña; consulta visibility y passwordProtected para conocer el modo y el estado de contraseña del proyecto.

Ejemplo

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

Respuesta

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

Cambiar acceso

Configura acceso público o con contraseña.

Solicitud
El id de la ruta es el ID del proyecto. JSON: visibility PUBLIC o PASSWORD; password puede omitirse si ya existe.
Respuesta
200: projectId, visibility, passwordProtected y proOnly.
Valores de campos
visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

Límites y comportamiento
PASSWORD requiere un plan apto y una contraseña de 6–100 caracteres si aún no existe. PUBLIC borra la contraseña; visibility omitida o vacía se interpreta como PUBLIC.
Detalles de campos y comportamiento

proOnly indica que la cuenta carece del derecho de acceso con contraseña; consulta visibility y passwordProtected para conocer el modo y el estado de contraseña del proyecto.

Si visibility se omite o está vacía, se aplica PUBLIC y se borra la contraseña guardada. La longitud se valida sin espacios en los extremos, pero PATCH guarda la entrada original, a diferencia de la subida de despliegue. Evita espacios al principio o al final de la contraseña.

Ejemplo

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

Respuesta

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

Listar versiones

Consulta historial de versiones y posibilidad de reversión.

Solicitud
El id de la ruta es el ID del proyecto. Consultas opcionales page (0) y size (20).
Respuesta
200: projectId, latestDeploymentId, limit, versions, page, size, totalElements y totalPages.
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

Límites y comportamiento
page empieza en 0 y size se limita a 1–100. El historial visible depende de la cuenta; revisa retained y canRollback de cada versión.

Ejemplo

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'

Respuesta

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

Revertir una versión

Crea un despliegue asíncrono a partir de una versión histórica retenida.

Solicitud
El id de la ruta es el ID del proyecto y deploymentId el de la versión; sin cuerpo.
Respuesta
200: rolledBack, status, deploymentSource, deploymentId y previewUrl (inicialmente null).
Valores de campos
status: QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED, BLOCKED

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

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

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

Límites y comportamiento
Solo versiones autoalojadas READY o SUPERSEDED con artefacto retenido. La URL fija cambia tras activarse correctamente; consulta el deploymentId devuelto. HTTP no exige confirmación del nombre.
Detalles de campos y comportamiento

La reversión crea un despliegue asíncrono sin consumir los cupos diario o mensual. rolledBack=true confirma la creación, no la activación; consulta el deploymentId devuelto.

Ejemplo

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

Respuesta

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

Consultar uso

Consulta límites y uso actual de la cuenta.

Solicitud
Sin parámetros ni cuerpo.
Respuesta
200: plan, subscriptionStatus, businessLimitsApplied, maxUploadMb, daily, monthly, monthlyUpload, concurrentBuilds y projects.
Valores de campos
plan / subscriptionPlan: FREE, PRO_MONTHLY, PRO_YEARLY

plan es el derecho vigente; subscriptionPlan es el plan suscrito y puede seguir siendo Pro tras perder el derecho.

subscriptionStatus: FREE, ACTIVE, PAST_DUE, CANCELED

Estado actual de la suscripción, independiente del estado del despliegue.

Límites y comportamiento
Los límites dependen de la política de la cuenta y pueden cambiar; usa los valores devueltos.
Detalles de campos y comportamiento

HTTP 402 puede indicar que se agotó el cupo diario o mensual de despliegues o el límite mensual de subida. Los límites efectivos y la aplicación de límites comerciales dependen de la política de la cuenta.

Ejemplo

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

Respuesta

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

Valores de campos

status

Ciclo de vida del despliegue: READY indica activación correcta, pero después puede cambiar a SUPERSEDED, EXPIRED o BLOCKED. Algunos despliegues BLOCKED pueden recuperarse tras corregir el contenido. Ningún estado se garantiza permanente; status por sí solo no garantiza el acceso a la URL.

QUEUED
En espera en la cola
BUILDING
En procesamiento por un trabajador
READY
Despliegue activado
SUPERSEDED
Sustituido por otro despliegue
FAILED
Despliegue fallido
EXPIRED
Vista previa caducada
BLOCKED
Despliegue bloqueado

urlStatus

Disponibilidad de URL calculada según el estado del backend; compruébala junto con el estado del despliegue. READY no garantiza acceso sin contraseña ni para todos los visitantes: siguen influyendo los controles de acceso, la red y el alojamiento.

READY
Disponible según el estado calculado por el backend
BLOCKED
Acceso bloqueado o restringido
EXPIRED
Vista previa caducada
UNAVAILABLE
No hay URL disponible actualmente

visibility / projectVisibility

En creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.

PUBLIC
Acceso público
PASSWORD
Acceso con contraseña
PRIVATE
Modo privado histórico; no se acepta en estas escrituras

source

El source opcional es una etiqueta de origen, no controla la autenticación. Si falta o no es válido en una petición con API key, se usa API.

CONSOLE
Etiqueta de consola
CLI
Etiqueta CLI
MCP
Etiqueta MCP
EXTENSION
Etiqueta de extensión
API
Etiqueta de API directa
GUEST
Etiqueta de invitado

deploymentSource

El origen de respuesta no es una enumeración cerrada: pueden aparecer valores históricos o futuros. La mayoría de detalles/listas convierte el REDEPLOY histórico en CONSOLE; versiones puede devolver el valor guardado.

CONSOLE
Consola o redespliegue histórico normalizado
CLI
CLI
MCP
MCP
EXTENSION
Extensión de editor
API
API directa
GUEST
Invitado
UNKNOWN
Origen desconocido
CONTENT_CHECK_RETRY
Reintento de comprobación técnica
ROLLBACK
Despliegue de reversión
SUBSCRIPTION_RESTORE
Restauración de suscripción
REDEPLOY
Origen de redespliegue histórico guardado

projectStatus

Estados conocidos del proyecto; admite otros valores históricos o futuros.

ACTIVE
Proyecto activo
BLOCKED
Proyecto bloqueado

hostingState

El estado de alojamiento es independiente de projectStatus y de las restricciones de contenido.

HOSTED
Proyecto alojado
ARCHIVED
Proyecto archivado

hostingStatus

Estado de alojamiento calculado; solo aparece cuando está disponible el servicio correspondiente.

BLOCKED
Proyecto o despliegue bloqueado
ARCHIVED
Proyecto archivado
RESTORING
Restauración de suscripción en curso
SUBSCRIPTION_ACTIVE
Alojamiento de pago activo
GRACE
Periodo de gracia de alojamiento de pago
FREE_ACTIVE
Alojamiento gratuito activo
EXPIRED
Caducado y restaurable
RESTORE_UNAVAILABLE
Restauración no disponible

plan / subscriptionPlan

plan es el derecho vigente; subscriptionPlan es el plan suscrito y puede seguir siendo Pro tras perder el derecho.

FREE
Plan gratuito
PRO_MONTHLY
Plan Pro mensual
PRO_YEARLY
Plan Pro anual

subscriptionStatus

Estado actual de la suscripción, independiente del estado del despliegue.

FREE
Estado de suscripción gratuita
ACTIVE
Suscripción activa
PAST_DUE
Pago vencido
CANCELED
Suscripción cancelada

contentRisk.status

contentRisk puede ser null; su status describe la comprobación, no el acceso a la URL.

PENDING
En espera de revisión
CHECKING
Revisión en curso
RETRYING
En espera de reintento
COMPLETED
Comprobación finalizada; el resultado aún puede ser UNKNOWN

contentRisk.decision

contentRisk.decision es el resultado de la revisión y no garantiza acceso a la vista previa.

PASS
Comprobación aprobada
HOLD
Retenido por riesgo
UNKNOWN
Sin decisión concluyente

contentRisk.riskLevel

Categoría de riesgo de contentRisk; UNKNOWN no significa seguro.

LOW
Riesgo bajo
MEDIUM
Riesgo medio
HIGH
Riesgo alto
UNKNOWN
Riesgo indeterminado

contentRisk.notificationStatus

Estado de notificación; ACCEPTED indica aceptación por el servicio de correo, no entrega. RUNNING se muestra como PENDING. Los valores conocidos no forman una lista cerrada.

PENDING
En espera de envío
RETRYING
En espera de reintento
ACCEPTED
Aceptado por el servicio de correo
FAILED
Falló el envío
SKIPPED_NO_RECIPIENT
Sin destinatario
SKIPPED
Notificación omitida
SUPERSEDED
Aviso sustituido por un estado posterior

contentRisk.findings[].limit.scope

Solo aparece en ciertos findings; los valores scope conocidos no son una lista cerrada. Las unidades de actual y maximum se indican abajo.

TOTAL_BYTES
Bytes totales del artefacto
FILE_BYTES
Bytes del archivo
MARKUP_NODES
Nodos de marcado
LINKED_SCRIPT_BYTES
Bytes de scripts enlazados
AI_TAG_CHARS_AT_LEAST
Mínimo de caracteres de una etiqueta HTML inicial sin cerrar
AI_CONTEXT_CHARS
Caracteres del contexto de comprobación
AI_CANDIDATES
Candidatos de seguridad
AI_BATCHES
Lotes de revisión de IA
AI_INPUT_CHARS
Caracteres de entrada de IA

error.code

Valores HTTP error.code habituales, no exhaustivos; consulta message y el details opcional.

INVALID_API_KEY
Clave ausente o inválida
ACCOUNT_BLOCKED
Cuenta bloqueada
INVALID_PARAM
Parámetro inválido
DAILY_QUOTA_EXCEEDED
Cuota diaria de despliegues agotada
MONTHLY_QUOTA_EXCEEDED
Cuota mensual de despliegues agotada
MONTHLY_UPLOAD_EXCEEDED
Cuota mensual de subida agotada
MAX_PROJECTS_EXCEEDED
Cuota de proyectos agotada
ZIP_TOO_LARGE
Archivo demasiado grande
DEPLOYMENT_NOT_REDEPLOYABLE
El despliegue no admite reintento directo
DEPLOYMENT_SUPERSEDED
Existe un despliegue posterior
PROJECT_URL_NOT_EXPIRED
La URL del proyecto aún no caducó
PROJECT_ARCHIVED
Proyecto archivado
ARTIFACT_NOT_RETAINED
Artefacto no retenido
PROJECT_NOT_FOUND
Proyecto inexistente o sin acceso
DEPLOYMENT_NOT_FOUND
Despliegue inexistente o sin acceso
PROJECT_BLOCKED
Proyecto bloqueado
DOWNGRADE_NOT_ALLOWED
Operación no permitida por el plan actual

failureCode

Valores failureCode habituales del despliegue asíncrono, no exhaustivos; consulta errorMessage y la disponibilidad de reintento.

UNBUILT_SOURCE
Código fuente sin compilar
EMPTY_ARCHIVE
Archivo comprimido vacío
MISSING_ENTRY_FILE
Falta el archivo de entrada
MULTIPLE_BUILD_OUTPUTS
Varias salidas compiladas
INVALID_PDF_FILE
PDF inválido
INVALID_ARCHIVE_PATH
Ruta del archivo comprimido inválida
ARCHIVE_READ_FAILED
No se pudo leer el archivo comprimido
UPLOAD_ARTIFACT_MISSING
Falta el artefacto subido
DEPLOYMENT_PROVIDER_FAILED
Falló el proveedor de alojamiento
CONTENT_CHECK_UNAVAILABLE
Comprobación de contenido no disponible
CONTENT_RISK_HIGH
Riesgo de contenido confirmado
MULTIPLE_PDF_FILES
Varios archivos PDF
ZIP_TOO_LARGE
Archivo comprimido demasiado grande
DEPLOYMENT_SUPERSEDED
Sustituido por un despliegue más reciente