API publique

Déploiements API

Déclenchez des déploiements, interrogez des enregistrements de déploiement et diffusez des événements de pipeline.

La surface des déploiements couvre les versions préliminaires, les publications de production et les flux d’événements de pipeline. Les chemins ne sont pas préfixés et ont pour racine https://api.showly.ai (il n'y a pas de préfixe de version).

Créer un déploiement

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "preview",
  "commitSha": "abc123...",
  "branch": "main"
}

C'est la seule route qui crée un déploiement (siteId est dans le chemin ; il n'y a pas de POST /deployments). Cela nécessite un en-tête Idempotency-Key — une clé manquante renvoie 428 et une clé rejouée en conflit renvoie 409. Il renvoie 202 + un enregistrement de déploiement dans l'état queued. La build s'exécute de manière asynchrone ; abonnez-vous à des événements ou interrogez l'enregistrement de déploiement.

{
  "ok": true,
  "data": {
    "id": "8c9d3e2a-4f1b-4c6d-9a2e-1f0b3c4d5e6f",
    "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "target": "preview",
    "status": "queued",
    "createdAt": "2026-05-14T15:00:00Z"
  }
}

Le champ d'environnement d'un enregistrement de déploiement est nommé target et est l'un des preview, staging ou production.

Publier en production

Les publications de production utilisent le même point de terminaison avec environment: "production" et un sourceDeploymentId nommant l'aperçu ready déjà construit en cours de promotion :

POST /sites/{siteId}/deploy
Authorization: Bearer <token>
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "environment": "production",
  "sourceDeploymentId": "dep_01HZX..."
}

La publication de production ne nécessite pas d’inscription OTP ou MFA. Cela nécessite encore un action de publication explicite et, lorsque l'espace de travail a approvalWorkflows activé, une approbation à la deuxième personne. Les agents utilisent request_publish lorsque cela la politique est activée ou la confirmation en deux étapes publish_site sinon.

Obtenez un déploiement

GET /deployments/{deploymentId}

Un statut de déploiement est exactement l'une des cinq valeurs suivantes :

queued → building → ready
                  ↘ failed
                  ↘ canceled

ready est l'état de réussite du terminal pour les déploiements en préversion et en production ; failed et canceled sont les états de défaillance du terminal. Il n'y a pas de statut built ou live. Un déploiement d'aperçu ready porte son adresse dans le champ url ; un déploiement de production ready dessert le parcours de production du site.

Progression de la création du flux

La progression de la construction est diffusée en direct sur SSE à partir de la surface des aperçus :

GET /previews/{deploymentId}/stream
Accept: text/event-stream

Le flux émet des transitions d'état et se ferme lorsque le déploiement atteint un état terminal. Pour les lectures post-hoc, deux points de terminaison simples couvrent la plupart des besoins :

GET /deployments/{deploymentId}/log?lineCount=200 — la queue du journal de construction capturée.
GET /deployments/{deploymentId}/diagnostics — un ensemble de défaillances structuré (étape, code d'erreur, queue de journal, hypothèses classées) conçu pour l'auto-débogage de l'agent.

Approuver/rejeter une demande de publication en production

POST /approvals/{requestId}/decision
Content-Type: application/json

{
  "decision": "approve" | "reject",
  "notes": "looks good"
}

Nécessite un abonnement utilisateur actif avec un rôle d'approbation autorisé. Il est interdit à l'acteur auteur d'approuver sa propre demande (séparation des tâches).

Restauration

Il n’y a pas de point de terminaison de restauration REST. Le retour à un déploiement antérieur est une opération d’interface utilisateur Web uniquement. Pour republier un aperçu ready précédemment, appelez POST /sites/{siteId}/deploy avec environment: "production" et l'identifiant de ce déploiement comme sourceDeploymentId ; l'approbation normale, les quotas et les barrières de sécurité s'appliquent toujours, mais l'inscription à l'OTP n'est pas requise.

Répertorier les déploiements

GET /deployments

Renvoie la liste complète de déploiement pour votre espace de travail sous forme de tableau simple : il n'y a pas encore de paramètres de filtre ou de pagination. Pour l'historique d'un seul site, utilisez GET /sites/{siteId}/deployments.

Erreurs spécifiques aux déploiements

Codes	Statut	Signification
`idempotency_key_required`	428	`POST /sites/{siteId}/deploy` a été appelé sans en-tête `Idempotency-Key`.
`idempotency_key_conflict`	409	Le `Idempotency-Key` fourni a déjà été utilisé avec une requête différente.
`deployment_not_found`	404	Token ne peut pas voir ce déploiement.
`approval_required`	428	La publication de production doit être approuvée avant de pouvoir être promue.
`source_deployment_required`	428	La publication de production doit nommer l'aperçu `ready` via `sourceDeploymentId`.
`self_approval_forbidden`	403	L'approbateur est l'acteur d'origine (séparation des tâches).
`source_deployment_not_found`	404	Le `sourceDeploymentId` n'existe pas ou n'est pas visible par votre token.
`source_deployment_not_ready`	409	Le déploiement source nommé n'est pas dans un état publiable (`ready`).

L'épuisement du quota de déploiement mensuel renvoie 402 avec une erreur de quota : mettez à niveau le plan ou attendez la réinitialisation mensuelle.

Motifs

Attendez la fin d'un déploiement (CI) :

DEP=$(curl ... | jq -r .data.id)
while :; do
  S=$(curl -sS .../deployments/$DEP | jq -r .data.status)
  [ "$S" = "ready" ] && break
  { [ "$S" = "failed" ] || [ "$S" = "canceled" ]; } && exit 1
  sleep 10
done

Lisez le journal de build :

curl -sS ".../deployments/$DEP/log?lineCount=500" \
  | jq -r '.data.lines[]' | tee build.log

Pour la plupart des automatisations, l'MCP create_preview outil est plus simple — le REST API existe pour les cas MCP ne convient pas.