Vue d’ensemble de la documentation

PREVIEWSHIP / HTTP API

Référence HTTP API

Créez et gérez des previews depuis votre serveur ou votre CI. Tous les exemples utilisent la même clé API et la même URL de base.

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 →
POST/v1/deployments

Cré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, BLOCKED

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.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

La création et PATCH acceptent seulement PUBLIC et PASSWORD ; PRIVATE peut apparaître dans les données historiques.

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

Le 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, REDEPLOY

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.

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"
}
GET/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, BLOCKED

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.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

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.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

La 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, REDEPLOY

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.

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, COMPLETED

contentRisk peut être null ; son status décrit la vérification et non l’accès à l’URL.

contentRisk.decision: PASS, HOLD, UNKNOWN

contentRisk.decision est le résultat de la vérification et ne garantit pas l’accès à l’aperçu.

contentRisk.riskLevel: LOW, MEDIUM, HIGH, UNKNOWN

Caté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_CHARS

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.

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

Valeurs 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"
}
GET/v1/deployments

Lister 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, BLOCKED

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.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

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.

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

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.

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
  }
}
POST/v1/deployments/{id}/retry-content-check

Relancer 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, BLOCKED

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.

visibility / projectVisibility: PUBLIC, PASSWORD, PRIVATE

La 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, REDEPLOY

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.

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"
}
GET/v1/projects

Lister 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, BLOCKED

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.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

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.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

La 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, REDEPLOY

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.

projectStatus: ACTIVE, BLOCKED

États connus du projet ; prévoyez aussi d’autres valeurs historiques ou futures.

hostingState: HOSTED, ARCHIVED

L’é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"
    }
  ]
}
GET/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, BLOCKED

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.

urlStatus: READY, BLOCKED, EXPIRED, UNAVAILABLE

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.

projectVisibility: PUBLIC, PASSWORD, PRIVATE

La 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, REDEPLOY

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.

projectStatus: ACTIVE, BLOCKED

États connus du projet ; prévoyez aussi d’autres valeurs historiques ou futures.

hostingState: HOSTED, ARCHIVED

L’é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"
}
DELETE/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
POST/v1/projects/{id}/redeploy-latest

Redé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, BLOCKED

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.

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

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.

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"
}
GET/v1/projects/{id}/access

Consulter 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, PRIVATE

La 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
}
PATCH/v1/projects/{id}/access

Modifier 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, PRIVATE

La 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
}
GET/v1/projects/{id}/versions

Lister 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, BLOCKED

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.

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

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.

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
}
POST/v1/projects/{id}/versions/{deploymentId}/rollback

Restaurer 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, BLOCKED

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.

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

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.

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
}
GET/v1/usage

Consulter 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_YEARLY

plan 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