REST API reference

The Page Lemon REST API lives at https://api.pagelemon.com/v1. Code agents with a shell use it to publish a folder in one command; AI agents should start with the publishing guide for AIs (Markdown).

Last updated 13 October 2026 · View as Markdown

Quick start

Publish a folder without an account (it stays online for 72 hours unless you keep it):

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

With an API token, the site goes straight into your account:

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

Hosts

Auth

Send credentials as Authorization: Bearer <token>.

We store only hashes of tokens, so a lost token can't be shown again. Create a new one instead.

Errors

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

agent_message is present when the AI should tell the user something. Pass it on in the user's language, with every link, code, number, date and domain exact; times are UTC, and *_at fields have them in ISO.

Deploy

POST /v1/deploy: one archive

The request body is the archive: .tar.gz, .tgz, .tar or .zip. The server detects the format from the bytes, so Content-Type is optional.

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

Every deploy replaces the whole site: files you leave out are removed from the live site. If every file sits under one top-level folder (dist/index.html, …), that folder is stripped.

Response 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 and claim_url appear only on an anonymous create.

POST /v1/deploy with JSON: inline files

For MCP clients and small sites: send Content-Type: application/json to the same endpoint.

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

encoding is utf8 or base64. Leave out site and base_revision to create a new site. The response is the same as above.

Patch: add "patch": true to send only the changed files plus "deleted": ["old.html"] on top of base_revision; everything else is kept. Same limits and checks; a stale base_revision is a 409 conflict.

Upload rules

Per site means the whole live site after a deploy; a patch counts the whole resulting site. On paid plans one site can use all of the plan's storage, but one request carries at most 90 MB (40 MB through MCP): send a bigger site as a first deploy, then the rest as patch deploys. Over a limit: 413 too_large with an agent_message to show.

• Rejected: symlinks, hard links, devices, absolute paths, .., and duplicate paths that differ only in case.
• Skipped and listed in skipped: .git/, node_modules/, .env*, *.map, *.pem, *.key; dotfiles except .well-known/; .DS_Store, Thumbs.db.
• Leak guard: text files are scanned for well-known kinds of secret keys and private keys. A hit returns 422 blocked_secret with {file, line, kind}. The key itself is never returned.
• Required: index.html at the root.
• Anonymous only: executables and installers are blocked, and each network gets a small number of anonymous sites and deploys. Claim or sign in for more.

Sites

Roles: viewers can read the site and its history. Editors can also deploy and roll back. Owners can also invite, rename and delete.

Account

Claiming sites, accepting invites, tokens and billing are handled at app.pagelemon.com.

Serving on pagelemon.dev

• / serves index.html. /about serves about.html or about/index.html.
• Missing files get the site's 404.html if present, otherwise ours.
• Single-page app fallback: if the site has no 404.html and the path has no file extension, index.html is served.
• Headers: X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Cache-Control: public, max-age=60 for HTML and max-age=300 for other files. Content types come from an allowlist; unknown types are served as application/octet-stream.
• Anonymous and Free sites get a small "Live on Page Lemon" badge before </body>. It's plain HTML and CSS, with no script, and includes a link to report the site.
• Expired or deleted sites return 410. Sites taken down for abuse return 451.

.pagelemon.json

After deploying, agents write this file in the project folder and add it to .gitignore, so the next session can update the same site:

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