Envoyez X-API-Key à chaque requête. Conservez la clé dans un coffre de secrets côté serveur, jamais dans le code du navigateur ou des fichiers publics. Avant les exemples, créez une clé API dans la console et définissez la variable d’environnement PREVIEWSHIP_API_KEY.
Conservez la clé API côté serveur ; les ressources sont limitées à son compte. Si un POST expire, consultez l’historique avant de réessayer pour éviter les doublons.
Les exemples de réponse ne montrent que certains champs ; limites, ID et dates sont indicatifs.
Les ID sont des entiers. Les dates comme createdAt et updatedAt sont des chaînes ISO 8601 UTC. Un champ omis est différent de null ; consultez chaque interface. Les domaines et quotas sont des exemples. La pagination commence à page 0 et le serveur normalise size entre 1 et 100. current indique si cet enregistrement est le déploiement pointé par latestDeploymentId du projet, retained indique la conservation de l’artefact, canRollback évalue l’état, le fournisseur et l’artefact, et proOnly la limitation des droits du compte. Ces booléens sont indépendants et ne garantissent pas la réussite de l’opération.
Erreurs courantes : 401 INVALID_API_KEY, 403 ACCOUNT_BLOCKED, 404 ressource absente, 409 conflit, 410 artefact indisponible, 413 fichier trop volumineux et 402 lorsque le quota quotidien ou mensuel de déploiement est épuisé. Les erreurs métier de l’application contiennent error.code et error.message ; error.details peut être absent. Les erreurs de passerelle ou de proxy peuvent avoir un autre format.
error.code →/v1/deploymentsCréer un déploiement
Importez un artefact prêt pour le navigateur et placez le déploiement en file d’attente.
- Requête
- multipart/form-data : projectName et zip obligatoires ; source, visibility et password facultatifs. zip accepte un ZIP statique ou un fichier HTML, Markdown ou PDF. projectName accepte au maximum 100 points de code Unicode. source est une étiquette d’origine : CONSOLE, CLI, MCP, EXTENSION, API ou GUEST ; absent ou invalide, il vaut API pour une requête par clé API. Il ne modifie pas l’authentification. Un nouveau mot de passe doit contenir 6 à 100 caractères après suppression des espaces aux extrémités ; un projet existant peut conserver son mot de passe enregistré.
- Réponse
- 201 : deploymentId, status, deploymentSource, visibility, createdAt. visibility est l’accès actuel ; le changement demandé s’applique après activation réussie.
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
visibility / projectVisibility:PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
source:CONSOLE,CLI,MCP,EXTENSION,API,GUESTLe source facultatif est une étiquette de provenance, sans effet sur l’authentification. Absent ou invalide avec une clé API, il vaut API.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
- Limites et comportement
- Sans visibility, un nouveau projet est PUBLIC et un projet existant conserve son accès. PASSWORD exige un forfait éligible. Les quotas et contrôles s’appliquent ; 201 ne signifie pas que le déploiement est terminé.
- Détails des champs et du comportement
Le champ multipart projectName doit être présent ; s’il est vide, le serveur essaie de le déduire du nom du fichier envoyé. HTTP 201 indique seulement la mise en file. La visibility renvoyée est l’accès actuel ; la modification demandée s’applique après activation. Lors d’un envoi de déploiement, les espaces aux extrémités d’un nouveau mot de passe sont retirés avant enregistrement.
Exemple
curl -X POST 'https://api.previewship.com/v1/deployments' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY" \
-F 'projectName=my-project' \
-F 'zip=@./site.zip'Réponse
{
"deploymentId": 42,
"status": "QUEUED",
"deploymentSource": "API",
"visibility": "PUBLIC",
"createdAt": "2026-11-13T10:00:00Z"
}/v1/deployments/{id}Consulter un déploiement
Consultez son état et la disponibilité de la preview.
- Requête
- Le id dans le chemin est l’ID du déploiement ; aucun corps.
- Réponse
- 200 : deploymentId, projectId, status, previewUrl, urlStatus, failureCode, errorMessage, contentRisk et disponibilité du nouvel essai.
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLEDisponibilité de l’URL calculée selon l’état du backend, à vérifier avec l’état du déploiement. READY ne garantit ni un accès sans mot de passe ni l’accès pour chaque visiteur ; les contrôles d’accès, le réseau et l’hébergement restent déterminants.
visibility / projectVisibility:PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEÉtat d’hébergement calculé ; renvoyé uniquement lorsque le service correspondant est disponible.
contentRisk.status:PENDING,CHECKING,RETRYING,COMPLETEDcontentRisk peut être null ; son status décrit la vérification et non l’accès à l’URL.
contentRisk.decision:PASS,HOLD,UNKNOWNcontentRisk.decision est le résultat de la vérification et ne garantit pas l’accès à l’aperçu.
contentRisk.riskLevel:LOW,MEDIUM,HIGH,UNKNOWNCatégorie de risque de contentRisk ; UNKNOWN ne signifie pas sûr.
contentRisk.notificationStatus:PENDING,RETRYING,ACCEPTED,FAILED,SKIPPED_NO_RECIPIENT,SKIPPED,SUPERSEDEDÉtat de notification ; ACCEPTED signifie accepté par le service de messagerie, pas livré. RUNNING est exposé comme PENDING. Les valeurs connues ne forment pas une liste fermée.
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_CHARSPrésent uniquement pour certains findings ; les valeurs scope connues ne constituent pas une liste fermée. Les unités de actual et maximum sont indiquées ci-dessous.
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_SUPERSEDEDValeurs failureCode courantes des déploiements asynchrones, non exhaustives ; consultez errorMessage et la possibilité de réessayer.
- Limites et comportement
- Seuls les déploiements du compte propriétaire sont accessibles. Interrogez avec un délai jusqu’à l’état final et utilisez le lien lorsqu’il est READY et disponible.
- Détails des champs et du comportement
status indique l’état du déploiement et urlStatus la disponibilité de la prévisualisation ; ils peuvent différer après une restriction ou expiration. contentRisk peut être null ; attempt, maxAttempts et nextRetryAt peuvent être omis. contentCheckRetryAvailable ne garantit pas que les droits actuels autorisent une nouvelle tentative ; un contentCheckRetryExpiresAt null peut indiquer qu’une tentative existante peut être récupérée. contentCheckUploadQuotaRestored marque le traitement de la compensation, sans prouver que le compteur de la période actuelle a changé. hostingStatus, hostingUntil, paidThrough, autoRenews et restorable sont conditionnels ; hostingUntil et paidThrough peuvent être null. contentRisk.findings est un tableau ; reasonCode est une chaîne extensible et limit peut être omis. verifiedSafeRecheck=true exige un PASS terminé, une version de modèle non vide et un verdict SAFE du modèle enregistré avec une confiance HIGH ; un PASS seul ne satisfait pas cette condition.
Exemple
curl 'https://api.previewship.com/v1/deployments/42' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"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/deploymentsLister les déploiements
Recherchez dans l’historique des déploiements du compte.
- Requête
- Paramètres facultatifs : page (0 par défaut), size (20 par défaut), status, q, days. status accepte ALL ou une seule valeur : QUEUED, BUILDING, READY, SUPERSEDED, FAILED, EXPIRED ou BLOCKED. q recherche une partie du nom du projet ou de l’URL de preview ; days filtre les N derniers jours.
- Réponse
- 200 : content, page, size, totalElements, totalPages et statusCounts. statusCounts tient compte de q et days, mais ignore le filtre status.
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLEDisponibilité de l’URL calculée selon l’état du backend, à vérifier avec l’état du déploiement. READY ne garantit ni un accès sans mot de passe ni l’accès pour chaque visiteur ; les contrôles d’accès, le réseau et l’hébergement restent déterminants.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
- Limites et comportement
- page commence à 0 ; size est limité à 1–100. days est limité à 365 ; une valeur non positive désactive le filtre temporel. status invalide renvoie 400.
Exemple
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'Réponse
{
"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-checkRelancer le contrôle de contenu
Relancez un contrôle après un échec technique récupérable sans réimporter le fichier.
- Requête
- Le id dans le chemin est l’ID du déploiement échoué ; aucun corps.
- Réponse
- 201 : deploymentId, status, deploymentSource, visibility et createdAt du nouvel essai.
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
visibility / projectVisibility:PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
- Limites et comportement
- Vérifiez contentCheckRetryAvailable. L’artefact doit être conservé et le projet et l’accès éligibles ; une version publiée plus récente empêche un nouvel essai. Répéter l’appel renvoie l’essai existant.
- Détails des champs et du comportement
Pour les comptes soumis à des limites commerciales, la première nouvelle tentative consomme les quotas quotidiens et mensuels de déploiements sans ajouter de volume d’envoi. Une demande répétée pour le même échec peut renvoyer le déploiement enfant existant sans consommer à nouveau les quotas.
Exemple
curl -X POST 'https://api.previewship.com/v1/deployments/42/retry-content-check' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"deploymentId": 43,
"status": "QUEUED",
"deploymentSource": "CONTENT_CHECK_RETRY",
"visibility": "PUBLIC",
"createdAt": "2026-11-13T10:05:00Z"
}/v1/projectsLister les projets
Listez les projets du compte propriétaire de la clé API.
- Requête
- Aucun paramètre ni corps.
- Réponse
- 200 : tableau projects avec ID, nom, dernier état, URL de preview et accès.
- Valeurs des champs
- latestDeploymentStatus:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLEDisponibilité de l’URL calculée selon l’état du backend, à vérifier avec l’état du déploiement. READY ne garantit ni un accès sans mot de passe ni l’accès pour chaque visiteur ; les contrôles d’accès, le réseau et l’hébergement restent déterminants.
projectVisibility:PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
latestDeploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
projectStatus:ACTIVE,BLOCKEDÉtats connus du projet ; prévoyez aussi d’autres valeurs historiques ou futures.
hostingState:HOSTED,ARCHIVEDL’état d’hébergement est indépendant de projectStatus et des restrictions de contenu.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEÉtat d’hébergement calculé ; renvoyé uniquement lorsque le service correspondant est disponible.
- Limites et comportement
- Seuls les projets du compte sont renvoyés ; les projets invités sont exclus.
- Détails des champs et du comportement
latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl et previewExpiresAt peuvent être null. hostingStatus, hostingUntil, paidThrough, autoRenews et restorable ne sont renvoyés que si l’état d’hébergement est disponible ; hostingUntil et paidThrough peuvent être null. Si le déploiement pointé par latest est absent, les valeurs affichées comme latestDeploymentStatus, latestDeploymentSource et previewUrl peuvent provenir d’un ancien déploiement Vercel READY et ne pas correspondre à latestDeploymentId.
Exemple
curl 'https://api.previewship.com/v1/projects' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"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}Consulter un projet
Lisez les informations du projet et de son dernier déploiement.
- Requête
- Le id dans le chemin est l’ID du projet ; aucun corps.
- Réponse
- 200 : id, name, latestDeploymentId, latestDeploymentStatus, previewUrl, projectVisibility, urlStatus et canRedeploy.
- Valeurs des champs
- latestDeploymentStatus:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
urlStatus:READY,BLOCKED,EXPIRED,UNAVAILABLEDisponibilité de l’URL calculée selon l’état du backend, à vérifier avec l’état du déploiement. READY ne garantit ni un accès sans mot de passe ni l’accès pour chaque visiteur ; les contrôles d’accès, le réseau et l’hébergement restent déterminants.
projectVisibility:PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
latestDeploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
projectStatus:ACTIVE,BLOCKEDÉtats connus du projet ; prévoyez aussi d’autres valeurs historiques ou futures.
hostingState:HOSTED,ARCHIVEDL’état d’hébergement est indépendant de projectStatus et des restrictions de contenu.
hostingStatus:BLOCKED,ARCHIVED,RESTORING,SUBSCRIPTION_ACTIVE,GRACE,FREE_ACTIVE,EXPIRED,RESTORE_UNAVAILABLEÉtat d’hébergement calculé ; renvoyé uniquement lorsque le service correspondant est disponible.
- Limites et comportement
- Seuls les projets propres non invités sont accessibles ; absent ou non détenu renvoie 404.
- Détails des champs et du comportement
latestDeploymentId, latestDeploymentStatus, latestDeploymentSource, latestDeployedAt, previewUrl et previewExpiresAt peuvent être null. hostingStatus, hostingUntil, paidThrough, autoRenews et restorable ne sont renvoyés que si l’état d’hébergement est disponible ; hostingUntil et paidThrough peuvent être null. Si le déploiement pointé par latest est absent, les valeurs affichées comme latestDeploymentStatus, latestDeploymentSource et previewUrl peuvent provenir d’un ancien déploiement Vercel READY et ne pas correspondre à latestDeploymentId.
Exemple
curl 'https://api.previewship.com/v1/projects/7' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"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}Supprimer un projet
Supprimez définitivement un projet et ses déploiements.
- Requête
- Le id dans le chemin est l’ID du projet ; aucun corps.
- Réponse
- 204 sans corps.
- Limites et comportement
- Supprime l’URL fixe, l’hébergement, les déploiements associés et l’élément Showcase. La HTTP API ne demande pas de confirmation du nom ; vérifiez la cible avant l’appel.
Exemple
curl -i -X DELETE 'https://api.previewship.com/v1/projects/7' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
HTTP 204 No Content/v1/projects/{id}/redeploy-latestRedéployer la dernière version
Placez en file un déploiement du dernier artefact conservé.
- Requête
- Le id dans le chemin est l’ID du projet ; aucun corps.
- Réponse
- 201 : deploymentId, projectId, status, deploymentSource et createdAt.
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
- Limites et comportement
- Projet éligible et artefact auto-hébergé conservé requis. L’URL doit normalement être expirée ; les comptes internes peuvent aussi redéployer une version READY. Interrogez le nouveau déploiement.
- Détails des champs et du comportement
Pour les comptes soumis à des limites commerciales, un redéploiement consomme les quotas quotidiens et mensuels de déploiements sans ajouter de volume d’envoi. Il est asynchrone.
Exemple
curl -X POST 'https://api.previewship.com/v1/projects/7/redeploy-latest' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"deploymentId": 43,
"projectId": 7,
"status": "QUEUED",
"deploymentSource": "CONSOLE",
"createdAt": "2026-11-13T10:05:00Z"
}/v1/projects/{id}/accessConsulter l’accès
Lisez le mode d’accès du projet.
- Requête
- Le id dans le chemin est l’ID du projet ; aucun corps.
- Réponse
- 200 : projectId, visibility, passwordProtected et proOnly.
- Valeurs des champs
- visibility / projectVisibility:
PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
- Limites et comportement
- Seuls les projets détenus sont accessibles ; le mot de passe lui-même n’est jamais renvoyé.
- Détails des champs et du comportement
proOnly indique que le compte ne dispose pas du droit d’accès par mot de passe ; consultez visibility et passwordProtected pour le mode et l’état du mot de passe du projet.
Exemple
curl 'https://api.previewship.com/v1/projects/7/access' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"projectId": 7,
"visibility": "PUBLIC",
"passwordProtected": false,
"proOnly": false
}/v1/projects/{id}/accessModifier l’accès
Définissez un accès public ou par mot de passe.
- Requête
- Le id dans le chemin est l’ID du projet. JSON : visibility PUBLIC ou PASSWORD ; password facultatif si un mot de passe existe déjà.
- Réponse
- 200 : projectId, visibility, passwordProtected et proOnly.
- Valeurs des champs
- visibility / projectVisibility:
PUBLIC,PASSWORD,PRIVATELa création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
- Limites et comportement
- PASSWORD exige un forfait éligible et un mot de passe de 6 à 100 caractères s’il n’y en a pas. PUBLIC efface le mot de passe ; visibility absente ou vide vaut PUBLIC.
- Détails des champs et du comportement
proOnly indique que le compte ne dispose pas du droit d’accès par mot de passe ; consultez visibility et passwordProtected pour le mode et l’état du mot de passe du projet.
Si visibility est omis ou vide, PUBLIC est appliqué et le mot de passe enregistré est supprimé. La longueur est vérifiée après suppression des espaces aux extrémités, mais PATCH enregistre la valeur d’origine, contrairement à l’envoi d’un déploiement. Évitez les espaces au début et à la fin du mot de passe.
Exemple
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"}'Réponse
{
"projectId": 7,
"visibility": "PUBLIC",
"passwordProtected": false,
"proOnly": false
}/v1/projects/{id}/versionsLister les versions
Consultez l’historique et la possibilité de restauration.
- Requête
- Le id dans le chemin est l’ID du projet. Paramètres facultatifs page (0 par défaut) et size (20 par défaut).
- Réponse
- 200 : projectId, latestDeploymentId, limit, versions, page, size, totalElements et totalPages.
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
- Limites et comportement
- page commence à 0 et size est limité à 1–100. L’historique visible dépend du compte ; vérifiez retained et canRollback pour chaque version.
Exemple
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'Réponse
{
"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}/rollbackRestaurer une version
Créez un déploiement asynchrone à partir d’une ancienne version conservée.
- Requête
- Le id dans le chemin est l’ID du projet et deploymentId celui de la version ; aucun corps.
- Réponse
- 200 : rolledBack, status, deploymentSource, deploymentId et previewUrl (initialement null).
- Valeurs des champs
- status:
QUEUED,BUILDING,READY,SUPERSEDED,FAILED,EXPIRED,BLOCKEDCycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
deploymentSource:CONSOLE,CLI,MCP,EXTENSION,API,GUEST,UNKNOWN,CONTENT_CHECK_RETRY,ROLLBACK,SUBSCRIPTION_RESTORE,REDEPLOYLa provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
- Limites et comportement
- Uniquement les versions auto-hébergées READY ou SUPERSEDED avec artefact conservé. L’URL fixe change après activation réussie ; interrogez le deploymentId renvoyé. HTTP n’exige pas de confirmation du nom.
- Détails des champs et du comportement
La restauration crée un déploiement asynchrone sans consommer les quotas quotidiens ou mensuels. rolledBack=true confirme la création, pas l’activation ; interrogez le deploymentId renvoyé.
Exemple
curl -X POST 'https://api.previewship.com/v1/projects/7/versions/42/rollback' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"rolledBack": true,
"status": "QUEUED",
"deploymentSource": "ROLLBACK",
"deploymentId": 43,
"previewUrl": null
}/v1/usageConsulter l’utilisation
Consultez les limites et l’utilisation actuelle du compte.
- Requête
- Aucun paramètre ni corps.
- Réponse
- 200 : plan, subscriptionStatus, businessLimitsApplied, maxUploadMb, daily, monthly, monthlyUpload, concurrentBuilds et projects.
- Valeurs des champs
- plan / subscriptionPlan:
FREE,PRO_MONTHLY,PRO_YEARLYplan représente le droit actif ; subscriptionPlan est le forfait souscrit et peut rester Pro après la fin du droit.
subscriptionStatus:FREE,ACTIVE,PAST_DUE,CANCELEDÉtat actuel de l’abonnement, indépendant de l’état du déploiement.
- Limites et comportement
- Les limites dépendent de la politique du compte et peuvent évoluer ; utilisez les valeurs renvoyées.
- Détails des champs et du comportement
HTTP 402 peut indiquer un dépassement des quotas quotidiens ou mensuels de déploiements ou du volume mensuel d’envoi. Les limites effectives et l’application des limites commerciales dépendent de la politique du compte.
Exemple
curl 'https://api.previewship.com/v1/usage' \
-H "X-API-Key: $PREVIEWSHIP_API_KEY"Réponse
{
"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
}
}Valeurs des champs
status
Cycle de vie du déploiement : READY indique une activation réussie, mais peut ensuite devenir SUPERSEDED, EXPIRED ou BLOCKED. Certains déploiements BLOCKED peuvent être rétablis après correction. Aucun état n’est garanti permanent ; status seul ne garantit pas l’accès à l’URL.
QUEUED- En attente dans la file
BUILDING- Traitement par un worker
READY- Déploiement activé
SUPERSEDED- Remplacé par un déploiement ultérieur
FAILED- Échec du déploiement
EXPIRED- Aperçu expiré
BLOCKED- Déploiement bloqué
urlStatus
Disponibilité de l’URL calculée selon l’état du backend, à vérifier avec l’état du déploiement. READY ne garantit ni un accès sans mot de passe ni l’accès pour chaque visiteur ; les contrôles d’accès, le réseau et l’hébergement restent déterminants.
READY- Disponibilité calculée selon l’état du backend
BLOCKED- Accès bloqué ou restreint
EXPIRED- Aperçu expiré
UNAVAILABLE- Aucune URL actuellement disponible
visibility / projectVisibility
La création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.
PUBLIC- Accès public
PASSWORD- Accès par mot de passe
PRIVATE- Mode privé historique ; non accepté par ces écritures
source
Le source facultatif est une étiquette de provenance, sans effet sur l’authentification. Absent ou invalide avec une clé API, il vaut API.
CONSOLE- Étiquette console
CLI- Étiquette CLI
MCP- Étiquette MCP
EXTENSION- Étiquette extension éditeur
API- Étiquette API directe
GUEST- Étiquette invité
deploymentSource
La provenance renvoyée n’est pas une énumération fermée : des valeurs historiques ou futures sont possibles. La plupart des détails/listes convertissent l’ancien REDEPLOY en CONSOLE ; les versions peuvent renvoyer la valeur enregistrée.
CONSOLE- Console ou ancien redéploiement normalisé
CLI- CLI
MCP- MCP
EXTENSION- Extension éditeur
API- API directe
GUEST- Invité
UNKNOWN- Provenance inconnue
CONTENT_CHECK_RETRY- Nouvelle tentative de vérification technique
ROLLBACK- Déploiement de restauration
SUBSCRIPTION_RESTORE- Restauration d’abonnement
REDEPLOY- Ancienne provenance de redéploiement enregistrée
projectStatus
États connus du projet ; prévoyez aussi d’autres valeurs historiques ou futures.
ACTIVE- Projet actif
BLOCKED- Projet bloqué
hostingState
L’état d’hébergement est indépendant de projectStatus et des restrictions de contenu.
HOSTED- Projet hébergé
ARCHIVED- Projet archivé
hostingStatus
État d’hébergement calculé ; renvoyé uniquement lorsque le service correspondant est disponible.
BLOCKED- Projet ou déploiement bloqué
ARCHIVED- Projet archivé
RESTORING- Restauration d’abonnement en cours
SUBSCRIPTION_ACTIVE- Hébergement payant actif
GRACE- Délai de grâce de l’hébergement payant
FREE_ACTIVE- Hébergement gratuit actif
EXPIRED- Expiré et restaurable
RESTORE_UNAVAILABLE- Restauration indisponible
plan / subscriptionPlan
plan représente le droit actif ; subscriptionPlan est le forfait souscrit et peut rester Pro après la fin du droit.
FREE- Forfait gratuit
PRO_MONTHLY- Forfait Pro mensuel
PRO_YEARLY- Forfait Pro annuel
subscriptionStatus
État actuel de l’abonnement, indépendant de l’état du déploiement.
FREE- État d’abonnement gratuit
ACTIVE- Abonnement actif
PAST_DUE- Paiement en retard
CANCELED- Abonnement annulé
contentRisk.status
contentRisk peut être null ; son status décrit la vérification et non l’accès à l’URL.
PENDING- En attente de vérification
CHECKING- Vérification en cours
RETRYING- En attente de nouvelle tentative
COMPLETED- Vérification terminée ; la décision peut rester UNKNOWN
contentRisk.decision
contentRisk.decision est le résultat de la vérification et ne garantit pas l’accès à l’aperçu.
PASS- Vérification réussie
HOLD- Retenu pour risque
UNKNOWN- Décision non déterminée
contentRisk.riskLevel
Catégorie de risque de contentRisk ; UNKNOWN ne signifie pas sûr.
LOW- Risque faible
MEDIUM- Risque moyen
HIGH- Risque élevé
UNKNOWN- Risque indéterminé
contentRisk.notificationStatus
État de notification ; ACCEPTED signifie accepté par le service de messagerie, pas livré. RUNNING est exposé comme PENDING. Les valeurs connues ne forment pas une liste fermée.
PENDING- En attente d’envoi
RETRYING- En attente de nouvelle tentative
ACCEPTED- Accepté par le service de messagerie
FAILED- Échec d’envoi
SKIPPED_NO_RECIPIENT- Aucun destinataire
SKIPPED- Notification ignorée
SUPERSEDED- Notification remplacée par un état ultérieur
contentRisk.findings[].limit.scope
Présent uniquement pour certains findings ; les valeurs scope connues ne constituent pas une liste fermée. Les unités de actual et maximum sont indiquées ci-dessous.
TOTAL_BYTES- Octets totaux de l’artefact
FILE_BYTES- Octets du fichier
MARKUP_NODES- Nombre de nœuds de balisage
LINKED_SCRIPT_BYTES- Octets de scripts liés
AI_TAG_CHARS_AT_LEAST- Nombre minimal de caractères d’une balise HTML ouvrante non terminée
AI_CONTEXT_CHARS- Caractères du contexte de vérification
AI_CANDIDATES- Candidats de sécurité
AI_BATCHES- Lots de vérification IA
AI_INPUT_CHARS- Caractères d’entrée IA
error.code
Valeurs HTTP error.code courantes, non exhaustives ; consultez message et details facultatif.
INVALID_API_KEY- Clé absente ou invalide
ACCOUNT_BLOCKED- Compte bloqué
INVALID_PARAM- Paramètre invalide
DAILY_QUOTA_EXCEEDED- Quota quotidien de déploiements dépassé
MONTHLY_QUOTA_EXCEEDED- Quota mensuel de déploiements dépassé
MONTHLY_UPLOAD_EXCEEDED- Quota mensuel d’import dépassé
MAX_PROJECTS_EXCEEDED- Quota de projets dépassé
ZIP_TOO_LARGE- Import trop volumineux
DEPLOYMENT_NOT_REDEPLOYABLE- Déploiement non réessayable directement
DEPLOYMENT_SUPERSEDED- Un déploiement plus récent existe
PROJECT_URL_NOT_EXPIRED- URL du projet non expirée
PROJECT_ARCHIVED- Projet archivé
ARTIFACT_NOT_RETAINED- Artefact non conservé
PROJECT_NOT_FOUND- Projet introuvable ou inaccessible
DEPLOYMENT_NOT_FOUND- Déploiement introuvable ou inaccessible
PROJECT_BLOCKED- Projet bloqué
DOWNGRADE_NOT_ALLOWED- Opération non autorisée par le forfait actuel
failureCode
Valeurs failureCode courantes des déploiements asynchrones, non exhaustives ; consultez errorMessage et la possibilité de réessayer.
UNBUILT_SOURCE- Code source non compilé
EMPTY_ARCHIVE- Archive vide
MISSING_ENTRY_FILE- Fichier d’entrée absent
MULTIPLE_BUILD_OUTPUTS- Plusieurs sorties de build
INVALID_PDF_FILE- PDF invalide
INVALID_ARCHIVE_PATH- Chemin d’archive invalide
ARCHIVE_READ_FAILED- Lecture de l’archive impossible
UPLOAD_ARTIFACT_MISSING- Artefact importé absent
DEPLOYMENT_PROVIDER_FAILED- Échec du fournisseur d’hébergement
CONTENT_CHECK_UNAVAILABLE- Vérification de contenu indisponible
CONTENT_RISK_HIGH- Risque de contenu confirmé
MULTIPLE_PDF_FILES- Plusieurs fichiers PDF
ZIP_TOO_LARGE- Archive trop volumineuse
DEPLOYMENT_SUPERSEDED- Remplacé par un déploiement plus récent