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 →/v1/deploymentsCrear 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,BLOCKEDCiclo 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,PRIVATEEn creación y PATCH solo se aceptan PUBLIC y PASSWORD; PRIVATE puede aparecer en lecturas históricas.
source:CONSOLE,CLI,MCP,EXTENSION,API,GUESTEl 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,REDEPLOYEl 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"
}/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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidad 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,PRIVATEEn 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,REDEPLOYEl 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_UNAVAILABLEEstado de alojamiento calculado; solo aparece cuando está disponible el servicio correspondiente.
contentRisk.status:PENDING,CHECKING,RETRYING,COMPLETEDcontentRisk puede ser null; su status describe la comprobación, no el acceso a la URL.
contentRisk.decision:PASS,HOLD,UNKNOWNcontentRisk.decision es el resultado de la revisión y no garantiza acceso a la vista previa.
contentRisk.riskLevel:LOW,MEDIUM,HIGH,UNKNOWNCategoría de riesgo de contentRisk; UNKNOWN no significa seguro.
contentRisk.notificationStatus:PENDING,RETRYING,ACCEPTED,FAILED,SKIPPED_NO_RECIPIENT,SKIPPED,SUPERSEDEDEstado 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_CHARSSolo 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_SUPERSEDEDValores 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"
}/v1/deploymentsListar 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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidad 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,REDEPLOYEl 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
}
}/v1/deployments/{id}/retry-content-checkReintentar 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,BLOCKEDCiclo 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,PRIVATEEn 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,REDEPLOYEl 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"
}/v1/projectsListar 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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidad 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,PRIVATEEn 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,REDEPLOYEl 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,BLOCKEDEstados conocidos del proyecto; admite otros valores históricos o futuros.
hostingState:HOSTED,ARCHIVEDEl estado de alojamiento es independiente de projectStatus y de las restricciones de contenido.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEEstado 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"
}
]
}/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,BLOCKEDCiclo 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,UNAVAILABLEDisponibilidad 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,PRIVATEEn 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,REDEPLOYEl 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,BLOCKEDEstados conocidos del proyecto; admite otros valores históricos o futuros.
hostingState:HOSTED,ARCHIVEDEl estado de alojamiento es independiente de projectStatus y de las restricciones de contenido.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEEstado 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"
}/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/v1/projects/{id}/redeploy-latestVolver 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,BLOCKEDCiclo 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,REDEPLOYEl 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"
}/v1/projects/{id}/accessConsultar 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,PRIVATEEn 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
}/v1/projects/{id}/accessCambiar 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,PRIVATEEn 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
}/v1/projects/{id}/versionsListar 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,BLOCKEDCiclo 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,REDEPLOYEl 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
}/v1/projects/{id}/versions/{deploymentId}/rollbackRevertir 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,BLOCKEDCiclo 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,REDEPLOYEl 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
}/v1/usageConsultar 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_YEARLYplan es el derecho vigente; subscriptionPlan es el plan suscrito y puede seguir siendo Pro tras perder el derecho.
subscriptionStatus:FREE,ACTIVE,PAST_DUE,CANCELEDEstado 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