Referência da API REST

A API REST do Page Lemon fica em https://api.pagelemon.com/v1. Agentes de código com acesso a um terminal a usam para publicar uma pasta com um único comando; agentes de IA devem começar pelo guia de publicação para IAs (Markdown).

Última atualização: 13 de outubro de 2026 · Ver em Markdown

Início rápido

Publique uma pasta sem conta (ela fica no ar por 72 horas, a menos que você a mantenha):

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

Com um token de API, o site vai direto para a sua conta:

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

Hosts

Autenticação

Envie as credenciais como Authorization: Bearer <token>.

Armazenamos apenas hashes dos tokens, então um token perdido não pode ser mostrado de novo. Crie um novo.

Erros

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

agent_message aparece quando a IA deve avisar algo ao usuário. Repasse o aviso no idioma do usuário, com todos os links, códigos, números, datas e domínios exatos; os horários são em UTC, e os campos *_at os trazem no formato ISO.

Publicar

POST /v1/deploy: um arquivo compactado

O corpo da requisição é o arquivo compactado: .tar.gz, .tgz, .tar ou .zip. O servidor detecta o formato pelos bytes, então Content-Type é opcional.

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

Cada publicação substitui o site inteiro: arquivos que você deixar de fora são removidos do site no ar. Se todos os arquivos estiverem dentro de uma única pasta de nível superior (dist/index.html, …), essa pasta é removida.

Resposta 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 e claim_url só aparecem em uma criação anônima.

POST /v1/deploy com JSON: arquivos inline

Para clientes MCP e sites pequenos: envie Content-Type: application/json para o mesmo endpoint.

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

encoding é utf8 ou base64. Deixe de fora site e base_revision para criar um site novo. A resposta é a mesma de cima.

Patch: adicione "patch": true para enviar só os files alterados mais "deleted": ["old.html"] sobre base_revision; todo o resto é mantido. Mesmos limites e verificações; um base_revision desatualizado é um 409 conflict.

Regras de upload

Por site significa o site inteiro no ar após um deploy; um patch conta o site inteiro resultante. Nos planos pagos, um site pode usar todo o armazenamento do plano, mas uma requisição leva no máximo 90 MB (40 MB pelo MCP): envie um site maior como primeiro deploy e o resto em deploys de patch. Acima do limite: 413 too_large com um agent_message para mostrar.

• Recusados: links simbólicos, hard links, dispositivos, caminhos absolutos, .. e caminhos duplicados que só diferem em maiúsculas/minúsculas.
• Ignorados e listados em skipped: .git/, node_modules/, .env*, *.map, *.pem, *.key; arquivos ocultos (dotfiles), exceto .well-known/; .DS_Store, Thumbs.db.
• Proteção contra vazamentos: arquivos de texto são verificados em busca de tipos conhecidos de chaves secretas e chaves privadas. Uma ocorrência retorna 422 blocked_secret com {file, line, kind}. A chave em si nunca é retornada.
• Obrigatório: index.html na raiz.
• Só para anônimos: executáveis e instaladores são bloqueados, e cada rede tem um número pequeno de sites e publicações anônimas. Resgate ou entre para ter mais.

Sites

Funções: leitores podem ver o site e seu histórico. Editores também podem publicar e reverter. Proprietários também podem convidar, renomear e apagar.

Conta

Resgatar sites, aceitar convites, tokens e cobrança são feitos em app.pagelemon.com.

Entrega em pagelemon.dev

• / serve index.html. /about serve about.html ou about/index.html.
• Arquivos inexistentes recebem o 404.html do site, se houver; caso contrário, o nosso.
• Fallback para single-page apps: se o site não tiver 404.html e o caminho não tiver extensão de arquivo, index.html é servido.
• Cabeçalhos: X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Cache-Control: public, max-age=60 para HTML e max-age=300 para os demais arquivos. Os tipos de conteúdo vêm de uma lista permitida; tipos desconhecidos são servidos como application/octet-stream.
• Sites anônimos e Free recebem um pequeno selo "No ar no Page Lemon" antes de </body>. É HTML e CSS simples, sem script, e inclui um link para denunciar o site.
• Sites expirados ou apagados retornam 410. Sites removidos por abuso retornam 451.

.pagelemon.json

Depois de publicar, os agentes gravam este arquivo na pasta do projeto e o adicionam ao .gitignore, para que a próxima sessão possa atualizar o mesmo site:

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