Référence de l’API REST

L’API REST de Page Lemon se trouve à https://api.pagelemon.com/v1. Les agents de code avec un shell l’utilisent pour publier un dossier en une seule commande ; les agents IA devraient commencer par le guide de publication pour les IA (Markdown).

Dernière mise à jour le 13 octobre 2026 · Voir en Markdown

Démarrage rapide

Publiez un dossier sans compte (il reste en ligne 72 heures, sauf si vous le conservez) :

tar -czf - -C dist . | curl -sS --data-binary @- https://api.pagelemon.com/v1/deploy

Avec un jeton d’API, le site arrive directement dans votre compte :

tar -czf - -C dist . | curl -sS -H "Authorization: Bearer $PAGELEMON_TOKEN" --data-binary @- https://api.pagelemon.com/v1/deploy

Hôtes

Authentification

Envoyez les identifiants sous la forme Authorization: Bearer <token>.

Nous ne stockons que des hachages des jetons : un jeton perdu ne peut pas être réaffiché. Créez-en un nouveau.

Erreurs

{ "error": { "code": "conflict", "message": "…" }, "agent_message": "…" }

agent_message est présent quand l'IA doit dire quelque chose à l'utilisateur. Transmettez-le dans la langue de l'utilisateur, en gardant exacts chaque lien, code, nombre, date et domaine ; les heures sont en UTC, et les champs *_at les donnent au format ISO.

Déploiement

POST /v1/deploy : une archive

Le corps de la requête est l’archive : .tar.gz, .tgz, .tar ou .zip. Le serveur détecte le format à partir des octets, donc Content-Type est facultatif.

tar -czf - -C <dir> . | curl -sS --data-binary @- https://api.pagelemon.com/v1/deploy

Chaque déploiement remplace tout le site : les fichiers que vous omettez sont retirés du site en ligne. Si tous les fichiers se trouvent dans un même dossier de premier niveau (dist/index.html, …), ce dossier est retiré.

Réponse 201 :

{
  "site": { "name": "brave-otter-4821", "url": "https://brave-otter-4821.pagelemon.dev", "claimed": false, "expires_at": "2026-10-14T14:40:00Z" },
  "revision": { "id": "rev_…", "number": 1, "files": 12, "bytes": 48213 },
  "site_token": "st_…",
  "claim_url": "https://app.pagelemon.com/claim/ct_…",
  "skipped": [".env", "node_modules/…"],
  "agent_message": "Your site is live at …"
}

site_token et claim_url n’apparaissent que lors d’une création anonyme.

POST /v1/deploy avec JSON : fichiers en ligne

Pour les clients MCP et les petits sites : envoyez Content-Type: application/json au même endpoint.

{ "site": "brave-otter-4821", "base_revision": "rev_…", "files": [ { "path": "index.html", "content": "<h1>Hi</h1>", "encoding": "utf8" } ] }

encoding vaut utf8 ou base64. Omettez site et base_revision pour créer un nouveau site. La réponse est la même que ci-dessus.

Patch : ajoutez "patch": true pour n’envoyer que les files modifiés plus "deleted": ["old.html"] par-dessus base_revision ; tout le reste est conservé. Mêmes limites et vérifications ; un base_revision obsolète donne un 409 conflict.

Règles d’envoi

« Par site » désigne l’ensemble du site en ligne après un déploiement ; un patch compte le site complet obtenu. Avec les forfaits payants, un site peut utiliser tout l’espace de stockage de le forfait, mais une requête ne peut transporter que 90 Mo au maximum (40 Mo via MCP) : envoyez un site plus gros en premier déploiement, puis le reste en déploiements patch. En cas de dépassement : 413 too_large avec un agent_message à afficher.

• Rejetés : liens symboliques, liens physiques, périphériques, chemins absolus, .., et chemins en double ne différant que par la casse.
• Ignorés et listés dans skipped : .git/, node_modules/, .env*, *.map, *.pem, *.key ; fichiers cachés sauf .well-known/ ; .DS_Store, Thumbs.db.
• Protection contre les fuites : les fichiers texte sont analysés pour détecter les types connus de clés secrètes et de clés privées. Une détection renvoie 422 blocked_secret avec {file, line, kind}. La clé elle-même n’est jamais renvoyée.
• Obligatoire : index.html à la racine.
• Anonyme uniquement : les exécutables et les installateurs sont bloqués, et chaque réseau dispose d’un petit nombre de sites et de déploiements anonymes. Récupérez le site ou connectez-vous pour en avoir plus.

Sites

Rôles : les lecteurs peuvent consulter le site et son historique. Les éditeurs peuvent aussi déployer et revenir en arrière. Les propriétaires peuvent aussi inviter, renommer et supprimer.

Compte

La récupération des sites, l’acceptation des invitations, les jetons et la facturation se gèrent sur app.pagelemon.com.

Diffusion sur pagelemon.dev

• / sert index.html. /about sert about.html ou about/index.html.
• Les fichiers manquants reçoivent la page 404.html du site si elle existe, sinon la nôtre.
• Repli pour application monopage : si le site n’a pas de 404.html et que le chemin n’a pas d’extension de fichier, index.html est servi.
• En-têtes : X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Cache-Control: public, max-age=60 pour le HTML et max-age=300 pour les autres fichiers. Les types de contenu proviennent d’une liste autorisée ; les types inconnus sont servis en application/octet-stream.
• Les sites anonymes et Gratuit affichent un petit badge "Live on Page Lemon" avant </body>. C’est du HTML et du CSS simples, sans script, avec un lien pour signaler le site.
• Les sites expirés ou supprimés renvoient 410. Les sites retirés pour abus renvoient 451.

.pagelemon.json

Après le déploiement, les agents écrivent ce fichier dans le dossier du projet et l’ajoutent à .gitignore, pour que la session suivante puisse mettre à jour le même site :

{ "site": "brave-otter-4821", "url": "https://brave-otter-4821.pagelemon.dev", "revision": "rev_…", "site_token": "st_…" }