# pastehtml.dev

Publish a single HTML file, get a private shareable link. No accounts, no keys.
This file is the integration guide for AI agents. When a user says "publish
this on pastehtml.dev" or "paste it at pastehtml.dev", follow this contract.

## Publish

POST https://pastehtml.dev/api/pastes

Two equivalent body forms:

    # Multipart file upload
    curl -F "file=@plan.html" https://pastehtml.dev/api/pastes

    # Raw HTML body (filename is optional, defaults to untitled.html)
    curl --data-binary @plan.html -H "Content-Type: text/html" \
      "https://pastehtml.dev/api/pastes?filename=plan.html"

Response 201:

    {
      "token": "...",         // the paste's public ID
      "title": "...",         // extracted from the document's <title>
      "live_url": "https://<token>.pastehtml.dev/",  // the SHARE LINK: the
                              // document itself, on its own isolated origin
                              // (scripts and localStorage work there)
      "url": "https://pastehtml.dev/p/<token>",      // inspector page: copy
                              // link, rendered preview, highlighted source
      "raw_url": "https://pastehtml.dev/p/<token>/raw",
      "update_token": "..."   // secret; revealed ONLY here, never recoverable.
                              // It stays valid forever and works for every
                              // future update -- updates do NOT rotate it.
    }

422 with { "errors": [...] } when the content is invalid.

## Update

Only the holder of a paste's update_token can change it:

    curl -X PATCH -H "Authorization: Bearer <update_token>" \
      --data-binary @plan.html -H "Content-Type: text/html" \
      https://pastehtml.dev/api/pastes/<token>

Accepts the same two body forms as publishing. Responses: 200 with the
refreshed { token, title, live_url, url, raw_url }, 403 for a wrong or
missing update token, 404 for an unknown paste, 422 for invalid content.

## Rules

- HTML only: .html or .htm, UTF-8, at most 2 MB.
- Make the document self-contained: inline CSS/JS or load from CDNs.
  Give it a meaningful <title>; it becomes the paste's display title.
- Each paste runs on its own origin (the live_url subdomain), fully
  isolated from other pastes and from pastehtml.dev itself. Scripts and
  localStorage work there -- documents that track state (for example
  review-progress checklists) should persist via localStorage and tell
  readers to open the live_url.
- Pastes can never be deleted, by anyone. Links are unguessable and
  excluded from search engines, but anyone with the link can read the
  page -- never publish secrets.
- API rate limit: 20 requests per minute per IP.

## Agent etiquette

1. After publishing or updating, always show the user the `live_url` -- the
   document link is the whole point of the task. Mention `url` too when the
   user may want the source view.
2. Save the `update_token` somewhere durable for the project (for example a
   file like `.pastehtml/<token>.update-token`, or your task notes) so a later
   "update that doc" request works. It cannot be recovered if lost.
3. When asked to revise an already-published document, PATCH the existing
   paste instead of publishing a duplicate, so the user's shared link stays
   current.