BrewPage Help — REST API & Developer Tools

BrewPage is a REST-first content host for HTML, Markdown, files, key-value entries, JSON documents and multi-file sites. No signup. No SDK. Every feature is reachable from curl, any HTTP client, or an AI agent. An optional profile keeps your publications in one place.

Quick start — publish HTML in one curl

Publish an HTML page (public namespace)

curl -X POST "https://brewpage.app/api/html?ns=public" \
  -H "Content-Type: text/html" \
  --data-binary @page.html
# response: {"link":"https://brewpage.app/public/aB3xK9mP2q","ownerToken":"...","manageUrl":"..."}

The response has the link, an Owner Token and a management link. Keep either one to edit or delete the page later. Lost the token? Add the page to your profile with its management link.

Content types

  • HTML — POST /api/html (5 MB, rendered with a CSP sandbox).
  • Markdown — POST /api/html?format=markdown (5 MB, rendered to styled HTML). Scripts, forms and embedded frames inside Markdown are removed; publish an HTML page for interactive content.
  • File — POST /api/files (5 MB generic, 20 MB video, 5 MB audio).
  • Multi-file site — POST /api/sites (ZIP, up to 20 MB / 200 files).
  • KV store — POST /api/kv to create, PUT /api/kv/{ns}/{id}/{key} to upsert (1 MB value, 1000 keys per store).
  • JSON document — POST /api/json (1 MB doc, 10 000 docs per namespace).

All resources share the same TTL model: default 15 days, max 30 days (90 with a profile). After TTL the nightly cleanup job permanently deletes the content — there is no recovery.

Namespaces and privacy

Public pages, sites and files without a password are listed in the public gallery and the sitemap, so Google, Bing and AI search can find and index them; use public for anything meant to be found or shared. Public pages are served right on the brewpage.app domain, which gives them the strongest reach in search; a page whose code needs its own origin (cookies, storage) gets its own subdomain automatically. Anyone can find and read a public publication: never put secrets, tokens or personal data there. JSON and KV are never listed. Other namespaces are unlisted; without a password, anyone with the link can read them. Password-protected resources are not listed, including those in the public namespace. Unlisted links and namespace names are not secrets; set a password to protect reader access.

REST requests without ns publish privately (unlisted); send ns=public to list. BrewPage MCP generates an unlisted namespace when omitted; explicitly pass public to list it. Agent skills and plugins follow their own publishing instructions.

Publish a password-protected page in the public namespace

curl -X POST "https://brewpage.app/api/html?ns=public" \
  -H "Content-Type: text/html" \
  -H "X-Password: secret123" \
  --data-binary @page.html

The homepage gallery shows public, password-less publications. Press the bookmark toggle in the gallery header to list your own pages, files and sites: those of this browser's Owner Token, or of your whole profile when this browser uses it.

Your publications are grouped:

  • Public — listed in the gallery and sitemap, search engines can index it; anyone with the link can open it. Hidden marks one you hid (link unchanged).
  • Password — link + password; never listed.
  • Private — not listed; anyone with the link can open it unless password-protected.

Your Owner Token is stored in this browser's localStorage and is managed automatically by the browser UI. You can view, paste or clear it any time on the Advanced Tools page.

Choose a publication address

New publications default to Domain (path in the API): a branded brewpage.app/<namespace>/<id> link with stricter HTML restrictions. Select Subdomain for the publication's own BrewPage subdomain with fewer HTML restrictions: scripts, embeds and navigation work natively. Password protection does not force either choice. Sites and HTML pages in a non-public namespace require a subdomain. Markdown, code, files, JSON and KV look the same on either address: the BrewPage viewer with a top bar and Download. Public pages without a password are listed in the gallery and the sitemap in both modes, and search engines can index them. Neither mode guarantees ranking or third-party widget compatibility. If HTML displays incorrectly in Domain mode, try Subdomain.

If you leave the switch alone, a new public HTML or Markdown page that clearly needs its own address (for example, it saves data in the browser or changes the address bar) may be published on a Subdomain automatically. The result shows why, and you can switch it back to Domain in Manage publication. Choosing a mode yourself is always respected.

Always copy the server-returned link. The separate lowercase host identifier is not your mixed-case publication ID, and stays reserved through updates and either direction of a hosting change. Namespace names may be visible in addresses, DNS/TLS metadata and logs; an unlisted address is not a secret. Existing publications keep their previous URLs and rendering. Publishing identical content may return an existing publication with its existing address; a requested mode does not change that publication.

On a subdomain, HTML pages and site HTML documents run natively (scripts, modules, forms and navigation work; no sandbox, no rewriting) and carry the small BrewPage attribution badge. Nothing else is injected, and files, JSON and KV are never modified. Opened in a browser, every other kind shows the BrewPage viewer there, as on a brewpage.app link; programs that request the address directly still receive the original bytes. Each new site has one dedicated host for its entire bundle, rather than a shared user or namespace host. Relative and root-relative links, directory indexes and multipage navigation use the publication host. Missing pages and assets return 404; there is no automatic SPA fallback. Platform management and APIs stay on brewpage.app; use the returned management link for owner controls.

New password-protected browser links contain no password. Enter it only after top-level navigation to unlock.brewpage.app, the trusted unlock gateway. The resulting reader session lasts up to one hour, capped by the publication expiry. Programmatic readers use X-Password on apex API endpoints. Native hosts use reader cookies, not forwarded owner/password headers. Browser unlock requires JavaScript, cookies and Web Locks support. Unsupported browsers show a notice; if automatic opening stops, use Continue or enable cookies and retry. Legacy password-link behavior remains unchanged.

Publication origins and host-only cookies reduce access between publications, with residual parent-domain cookie interference. Protected BrewPage-mode publications also retain exposure to unchanged legacy executable content on the apex. Authored service workers can control their own publication and retain already delivered content; revoking server access cannot erase offline caches, downloads or copies. These are limited boundaries, not complete isolation or offline revocation guarantees.

Owners can switch new publications without a required subdomain between modes from their management page or the versioned hosting API. Sites, HTML pages in a non-public namespace and legacy publications have locked hosting. Content, password, owner token and expiry remain unchanged by a mode switch. Owners of new password-protected publications can revoke browser reader access from management or POST /api/{type}/{ns}/{id}/access/revoke with their owner token. Readers must unlock again; other publications remain accessible, and downloaded or offline copies cannot be erased.

Owner Token — edit & delete

Every publish returns an ownerToken. Send it as X-Owner-Token to edit or delete:

Delete a page with its Owner Token

curl -X DELETE https://brewpage.app/api/html/public/aB3xK9mP2q \
  -H "X-Owner-Token: $OWNER_TOKEN"

Replace a page in place (same short URL)

curl -X PUT https://brewpage.app/api/html/public/aB3xK9mP2q \
  -H "Content-Type: text/html" \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  --data-binary @page-v2.html

Tokens are hashed (bcrypt) on the server — the plaintext exists only in the original response. The browser UI keeps the token in localStorage as a convenience. Clear or paste a different token any time from Advanced Tools.

Manage a publication

Every publish also returns a management link: a private link that edits or deletes this page from any device. Keep it to yourself. We never ask for this link on a publication page.

  • Hide / Show — Hide takes a public page out of the gallery and search; the link keeps working.
  • Change link — gives the page a new address. The old link stops working everywhere.
  • Reset management link — makes a new management link. The old one stops working; the page link stays.
  • Extend 90 days — signed in: keeps the page 90 days from today. Never shortens it.
  • Stats — daily views, link previews and countries per page. Bot and crawler reads are shown apart, not counted as views.
  • Older pages — published before 5 October 2026: read-only. Update publishes a new copy; the old link stays until it expires. Delete and Hide still work.

Every action is also in the API with X-Owner-Token: OpenAPI spec.

Profile — optional

Publishing needs no account. A profile on account.brewpage.app keeps your publications in one place, on any device. Sign in with Google or with email and password.

  • Publications — one list with previews and stats. Add a page by its management link.
  • Connect this browser — publish and edit from this browser as your profile.
  • Tokens — for agents and scripts. Publish: create and manage all your pages. Admin: also add and delete tokens by API. Expiry is optional, set when you create one. Deleting a token keeps its pages.
  • 90-day storage — pages published with a profile token can live up to 90 days.

KV store

Create a KV store

curl -X POST "https://brewpage.app/api/kv?ns=public" \
  -H "Content-Type: application/json" \
  -d '{"key":"api_url","value":"https://example.com"}'

Upsert a key

curl -X PUT https://brewpage.app/api/kv/public/{id}/api_url \
  -H "Content-Type: application/json" \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -d '{"value":"https://example.com"}'

Read a key

curl https://brewpage.app/api/kv/public/{id}/api_url

JSON document storage

Create a JSON document

curl -X POST "https://brewpage.app/api/json?ns=public" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hi","body":"..."}'

Fetch a JSON document by id

curl https://brewpage.app/api/json/public/{id}

Multi-file site

Upload a ZIP with an index.html at the root to publish a static site (CSS, JS, images and fonts allowed; up to 200 files, 20 MB total uncompressed, 5 MB per file, 25 MB per upload request). System files such as .DS_Store and __MACOSX/ are skipped and not counted. Current limits: GET /api/limits.

Zip a site and publish it

zip -r site.zip index.html assets/
curl -X POST "https://brewpage.app/api/sites?ns=public" \
  -F "archive=@site.zip"
# response for a new site: {"link":"https://c7k2v9m4t8.brewpage.app/","ownerToken":"..."}

Replace the full bundle with PUT /api/sites/public/{id} and X-Owner-Token, using the same multipart fields. The publication address stays unchanged.

Rate limits

Uploads
Rate-limited per IP — exceeding the limit returns 429 with a Retry-After header.
Reads
Also rate-limited per IP.
429 response
Includes a Retry-After header so clients can back off.
Access logs
IP, user-agent, referer, status, latency kept for 30 days, then deleted.

Interactive tools

Go to Advanced Tools for the in-browser UI — Owner Token inspector, KV store, file manager, JSON editor.

Learn more

Contact us

To flag a harmful page, use Report abuse.