Referencia de la API REST

La API REST de Page Lemon está en https://api.pagelemon.com/v1. Los agentes de código con terminal la usan para publicar una carpeta con un solo comando; los agentes de IA deben empezar por la guía de publicación para IA (Markdown).

Última actualización: 13 de octubre de 2026 · Ver en Markdown

Inicio rápido

Publica una carpeta sin cuenta (queda en línea 72 horas si no la conservas):

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

Con un token de API, el sitio va directo a tu cuenta:

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

Hosts

Autenticación

Envía las credenciales como Authorization: Bearer <token>.

Solo almacenamos hashes de los tokens, así que un token perdido no se puede volver a mostrar. Crea uno nuevo.

Errores

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

agent_message aparece cuando la IA debe decirle algo a la persona usuaria. Transmítelo en el idioma de la persona, con cada enlace, código, número, fecha y dominio exactos; las horas están en UTC, y los campos *_at las traen en formato ISO.

Despliegue

POST /v1/deploy: un archivo comprimido

El cuerpo de la solicitud es el archivo comprimido: .tar.gz, .tgz, .tar o .zip. El servidor detecta el formato a partir de los bytes, así que Content-Type es opcional.

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

Cada despliegue reemplaza el sitio entero: los archivos que no incluyas se eliminan del sitio en línea. Si todos los archivos están dentro de una única carpeta de nivel superior (dist/index.html, …), esa carpeta se elimina de las rutas.

Respuesta 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 y claim_url solo aparecen en una creación anónima.

POST /v1/deploy con JSON: archivos en línea

Para clientes MCP y sitios pequeños: envía Content-Type: application/json al mismo endpoint.

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

encoding es utf8 o base64. Omite site y base_revision para crear un sitio nuevo. La respuesta es la misma que arriba.

Parche: añade "patch": true para enviar solo los files modificados más "deleted": ["old.html"] sobre base_revision; todo lo demás se conserva. Mismos límites y comprobaciones; un base_revision desactualizado da 409 conflict.

Reglas de subida

Por sitio significa el sitio completo en línea tras un despliegue; un parche cuenta el sitio completo resultante. En los planes de pago un sitio puede usar todo el almacenamiento del plan, pero una solicitud lleva como máximo 90 MB (40 MB por MCP): envía un sitio más grande como primer despliegue y el resto como despliegues de parche. Si superas un límite: 413 too_large con un agent_message para mostrar.

• Se rechazan: enlaces simbólicos, enlaces duros, dispositivos, rutas absolutas, .. y rutas duplicadas que solo se diferencian en mayúsculas y minúsculas.
• Se omiten y se enumeran en skipped: .git/, node_modules/, .env*, *.map, *.pem, *.key; archivos ocultos (dotfiles) excepto .well-known/; .DS_Store, Thumbs.db.
• Protección contra filtraciones: los archivos de texto se analizan en busca de tipos conocidos de claves secretas y claves privadas. Una coincidencia devuelve 422 blocked_secret con {file, line, kind}. La clave en sí nunca se devuelve.
• Obligatorio: index.html en la raíz.
• Solo anónimos: se bloquean ejecutables e instaladores, y cada red dispone de un número reducido de sitios y despliegues anónimos. Reclama el sitio o inicia sesión para tener más.

Sitios

Roles: los lectores pueden ver el sitio y su historial. Los editores además pueden desplegar y revertir. Los propietarios además pueden invitar, renombrar y eliminar.

Cuenta

Reclamar sitios, aceptar invitaciones, los tokens y la facturación se gestionan en app.pagelemon.com.

Servicio en pagelemon.dev

• / sirve index.html. /about sirve about.html o about/index.html.
• Los archivos que no existen reciben el 404.html del sitio si lo hay; si no, el nuestro.
• Alternativa para aplicaciones de una sola página: si el sitio no tiene 404.html y la ruta no tiene extensión de archivo, se sirve index.html.
• Encabezados: X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Cache-Control: public, max-age=60 para HTML y max-age=300 para los demás archivos. Los tipos de contenido salen de una lista permitida; los tipos desconocidos se sirven como application/octet-stream.
• Los sitios anónimos y Free llevan un pequeño distintivo "Publicado en Page Lemon" antes de </body>. Es HTML y CSS simples, sin scripts, e incluye un enlace para denunciar el sitio.
• Los sitios caducados o eliminados devuelven 410. Los sitios retirados por abuso devuelven 451.

.pagelemon.json

Después de desplegar, los agentes escriben este archivo en la carpeta del proyecto y lo añaden a .gitignore, para que la siguiente sesión pueda actualizar el mismo sitio:

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