API des sites

La surface des sites vous permet d'énumérer, d'inspecter et de créer des sites dans un espace de travail. Le REST API n'a pas de préfixe de version : tous les chemins ci-dessous ont pour racine https://api.showly.ai.

Liste des sites

GET /sites
Authorization: Bearer <token>

Renvoie chaque site que le jeton peut voir (un tableau simple - pas encore de pagination), plus un objet frère entitlements avec les majuscules du site de l'espace de travail.

{
  "ok": true,
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "projectId": "9b2f1c44-0d31-4c19-8a77-0f4bd4a1c001",
      "slug": "marketing-site",
      "name": "Marketing site",
      "framework": "next-export",
      "status": "active",
      "repositoryUrl": "https://github.com/acme/marketing",
      "productionUrl": "https://marketing-site.showly.site",
      "createdAt": "2026-03-01T10:14:22Z",
      "updatedAt": "2026-07-01T08:03:10Z"
    }
  ],
  "entitlements": {
    "maxSites": "unlimited",
    "currentSites": 3,
    "maxLiveSites": "unlimited",
    "currentLiveSites": 1
  }
}

Les identifiants de site sont des UUID. La valeur framework est une chaîne de forme libre automatiquement détectée par le constructeur (par exemple next-export, astro, static-html).

Allocations de sites

maxLiveSites est le nombre de sites en ligne compris dans l’offre. Sa valeur est "unlimited" pour Free comme pour Pro. Un contrat personnalisé ou une dérogation peut encore renvoyer une valeur finie, vérifiée lors de la publication.

maxSites couvre tous les enregistrements de sites actifs, y compris les sites qui n’ont qu’un aperçu. Sa valeur est également "unlimited" sur toutes les offres de base. Une valeur finie n’apparaît que lorsqu’un opérateur applique une dérogation explicite à l’espace de travail ; passer de Free à Pro n’ajoute pas de sites. Les aperçus de l’espace de travail n’expirent pas.

Obtenez un seul site

GET /sites/{siteId}

Renvoie le site ainsi que le manifeste actuel et le résumé du déploiement le plus récent.

Créer un site

POST /sites
Content-Type: application/json

{
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Docs",
  "slug": "docs",
  "repositoryUrl": "https://github.com/acme/docs"
}

Renvoie 201 et le site créé. projectId est l’UUID du projet auquel appartient le site. slug doit correspondre à ^[a-z0-9-]+$ et être unique dans l’espace de travail ; en cas de conflit, l’API renvoie 409 avec error.code: "slug_taken". framework et repositoryUrl sont facultatifs.

La configuration de build se trouve dans un manifeste showly.json validé dans le référentiel, pas dans le corps de création. Le constructeur détecte automatiquement le framework et lit rootDirectory, runtime, buildCommand, output et les champs associés de ce fichier. Voir Manifeste du site pour le schéma complet.

Déployer des cibles

Les cibles de déploiement sont configurées au niveau de l'organisation, et non par site. Ils sont montés à /deployment-targets :

Une cible porte un provider, un mode et un runtime. Le point final de la capacité est la source de vérité pour les combinaisons possibles dans l’environnement actuel ; énumération les valeurs dans un schéma API ne promettent pas qu'un fournisseur est provisionné. Les combinaisons non prises en charge renvoient 400 deployment_target_not_implemented.

L'enregistrement d'une cible de déploiement dans votre propre compte cloud nécessite le byoCloudTargets droit et un utilisateur acteur. Un bot utilisant uniquement des jetons ne peut pas créer, mettre à jour ou supprimer une cible de votre propre cloud.

Exemple Curl : création de bout en bout + premier déploiement

# 1. Create the site
SITE=$(curl -sS -X POST https://api.showly.ai/sites \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Demo", "slug": "demo", "repositoryUrl": "https://github.com/acme/demo" }' \
  | jq -r '.data.id')

# 2. Inspect the site (and the auto-detected manifest)
curl -sS "https://api.showly.ai/sites/$SITE" \
  -H "authorization: bearer $SHOWLY_TOKEN"

# 3. Request a preview deployment (siteId in the path; Idempotency-Key required)
curl -sS -X POST "https://api.showly.ai/sites/$SITE/deploy" \
  -H "authorization: bearer $SHOWLY_TOKEN" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{ "environment": "preview" }'

L'appel de création de déploiement renvoie 202. L'en-tête Idempotency-Key est requis sur POST /sites/:siteId/deploy ; sans cela, la requête renvoie 428 et une nouvelle tentative conflictuelle renvoie 409. Voir Déploiements pour le reste du cycle de vie du déploiement.

Archiver et restaurer

Supprimer un site l'archive : il disparaît de GET /sites mais reste répertorié par GET /sites/archived. Un site n'est pas archivé uniquement parce qu'il reste en Preview. La suppression explicite rend son slug réutilisable. Si l'espace de travail dispose d'un remplacement explicite et fini de maxSites, la suppression libère également une de ces places remplacées.

Rapportez-en un avec :

POST /sites/:siteId/restore

Le site revient vide et prêt à être redéployé — ses anciens déploiements ne le sont pas ressuscités, car leurs artefacts de construction ont déjà été récupérés. La restauration consomme un emplacement de site, elle renvoie donc 402 si vous êtes à votre maxSites allocation, et 404 si l'identifiant est inconnu, appartient à un autre espace de travail ou est déjà actif.

Erreurs