BrewPage API — REST Reference

Publish HTML, Markdown, files, KV entries, JSON documents, and multi-file sites over HTTPS, and let published pages save what visitors enter. No signup required to publish. Keep the X-Owner-Token or the management link from the response to edit or delete later.

API docs & tools

Human-oriented walk-through of every resource: /help.

Basics — URL, auth, limits

Base URL
https://brewpage.app/api/*
Publish auth
None. Every POST returns ownerToken and manageUrl; send the token as X-Owner-Token to edit or delete later.
Namespace
ns=public: listed in the gallery and sitemap, indexed by Google, Bing and AI search; never for secrets or personal data. No ns (default): private, unlisted, opened only by its link. JSON and KV are never listed. Other names: 1-32 of a-z, 0-9, hyphen; unlisted.
Password
Optional X-Password header for access-gated content. Programmatic readers use this header on apex API endpoints. New browser links stay clean and use trusted unlock; legacy ?p= behavior is unchanged.
Admin
/api/admin/* requires X-Admin-Password. Not for end-user traffic.
Rate limits
Uploads & reads are rate-limited per IP. 429 responses include Retry-After. Details: /help#rate-limits.
User-Agent
Required on every request. Format AgentName/version.
TTL
In days: up to 30 days without an account, up to 90 with a free profile (send its X-Owner-Token); a default applies when ttl is omitted. Set it with the ttl query parameter. Expired content is permanently deleted by the nightly cleanup job.

Quick start — curl

Publish HTML (public)

curl -X POST "https://brewpage.app/api/html?ns=public" \
  -H "Content-Type: application/json" \
  -d '{"content":"<h1>Hello</h1>"}'

Response: {"id":"aB3xK9mP2q","namespace":"public","link":"https://brewpage.app/public/aB3xK9mP2q","ownerToken":"...","manageUrl":"..."}. Give the user link and manageUrl (private: its holder can edit or delete); keep ownerToken for updates.

Upload a file

curl -X POST "https://brewpage.app/api/files?ns=public" \
  -F "file=@report.pdf"

Write a KV entry

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

Store a JSON document

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

Update in place (PUT)

Already published? Replace the content without changing the short URL — PUT /api/html/{ns}/{id}, PUT /api/json/{ns}/{id}, PUT /api/kv/{ns}/{id}/{key}. Send the original X-Owner-Token.

curl -X PUT https://brewpage.app/api/html/public/aB3xK9mP2q \
  -H "Content-Type: application/json" \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -d '{"content":"<h1>v2</h1>"}'

Multi-file sites republish the same way — PUT /api/sites/{ns}/{id} with your X-Owner-Token does a full replace of the file set, keeping the same short URL and ID.

curl -X PUT https://brewpage.app/api/sites/public/aB3xK9mP2q \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -F "archive=@site-v2.zip"

Immutable on update: filename, showTopBar. To change those, delete and recreate. HTML and site updates: ?tags= (sites: form field) replaces the stored tags; omit it to keep them. Token workflow: /help#owner-token.

Old publications (made before 5 October 2026) are read-only: 409 OLD_PUBLICATION_READ_ONLY; POST the content to its createUrl (same namespace), give the user the new link and manageUrl and keep the new owner token for later updates. HTML also adds republishUrl (browser). The old link keeps working; delete still works.

Owner actions

With X-Owner-Token: list or unlist in gallery & search, make a public page private, hide the badge (profile, up to 5 pages), change link, reset management link, set a password, extend 90 days (profile token), rename (profile), per-page stats. Profile tokens: scope publish or admin (also manages tokens), optional expiry at creation. Endpoints: OpenAPI. Guide: /help#manage.

Rename an HTML page (Markdown and code included) or a site in a profile: POST /api/{html|sites}/{ns}/{id}/title with X-Owner-Token or X-Manage-Key and {"title":"…"}, 1-200 characters on one line; "" restores the title from the content. Returns 200 {"title","custom"}. The new title shows in your profile, the gallery and link previews, and stays when you republish; the page's own <title> is unchanged. Files, JSON and KV have no rename. Errors: 400 TITLE_INVALID, 403 OWNER_AUTHORIZATION_FAILED (wrong proof or not in a profile), 404 PUBLICATION_UNAVAILABLE, 409 OLD_PUBLICATION_READ_ONLY, 429.

Hide or show the badge: POST /api/{type}/{ns}/{id}/badge with {"hidden":true} or false, for a page in a profile; returns 200 {"hidden","used","limit","notices"}, 409 BADGE_HIDDEN_LIMIT past 5 pages. Make a public page private: POST /api/{type}/{ns}/{id}/private returns a new private link and manageUrl (give both to the user); the public link answers 410, views and stats stay. One-way. Errors: 409 NOT_PUBLIC, 429 ROTATE_LIMITED.

Notifications of a profile (the header bell; Help) with X-Owner-Token set to a token added to exactly one profile: GET /api/profile/notifications (section=notices|activity, unread=true, limit 1-50, cursor) returns {items, nextCursor, unread}; GET .../unread-count; POST .../read with {"ids":[...]} or {"all":true}; GET|PUT .../settings (enabled, channel site or site_email, groups; changing them needs scope admin); GET|PUT .../pages/{html|sites}/{ns}/{id} with {"entries":true|false} turns notices of new entries on one page on or off. Errors: 403 PROFILE_TOKEN_REQUIRED, 403 ADMIN_TOKEN_REQUIRED.

Publication hosting

New publications with persisted routingCohort: "new-v1" support Domain (path, a branded brewpage.app link) and Subdomain (subdomain, the publication's own BrewPage subdomain). Sites and non-public HTML pages are always subdomain. Other publications default to the BrewPage path address, including password-protected ones, and may choose a subdomain. Public pages without a password can be indexed by search engines in both modes. Send X-Delivery-Mode: path or subdomain on HTML, Markdown, file, JSON, KV or site creation; the response states the mode in effect (effectiveDeliveryMode, deliveryNotice). Any kind may use a subdomain: HTML pages and sites are served there as authored documents, every other kind opens in the same BrewPage viewer (top bar, Download) on either address. This header is transport metadata, never a field added to an authored JSON document or upload. PUT keeps the address mode (change it with the hosting change); a PUT that makes a non-public BrewPage-link page HTML moves it to a subdomain, and the old link redirects there.

POST /api/html without X-Delivery-Mode: a public HTML or Markdown page whose own inline code clearly needs browser features a BrewPage link (path) does not provide may be published on its own subdomain. The response then carries deliveryModeReason: "auto:<codes>", a plain-text deliveryNotice and a subdomain link; requestedDeliveryMode stays null. Codes are comma-separated: storage, cookies, history, downloads, top-navigation, media-capture (camera, microphone, screen or location), pointer-lock, embeds, fullscreen. An explicit header always wins; with path, and on PUT or an idempotent duplicate (neither changes the address), the response may carry deliveryModeReason: "advisory:<codes>" and a notice instead. Both fields are absent when nothing applies, and not every such page is recognized. To move a page back, change its hosting with "deliveryMode":"path".

Follow the returned link; do not construct a hostname from the mixed-case resource ID. Hosts use a separate permanent lowercase identifier. New responses include managementLink, routingCohort, deliveryMode, requestedDeliveryMode, effectiveDeliveryMode, deliveryModeMatched, access, modeLocked and hostingVersion. A plain-text deliveryNotice with a deliveryModeReason code explains the mode in effect (both absent when nothing applies). Unrequested modes have null request/match fields. access is public, unlisted or protected. Management and owner API links remain on the apex.

A create request can return an existing publication. Its identity, cohort, mode and link remain those of the existing publication; a requested mode does not change it. Matching between new publications is supported; matching against legacy publications is not guaranteed. Legacy publications retain their URLs and behavior, have locked hosting, and report routingCohort: "old" with null mode/version/management metadata.

Owner-only GET /api/{type}/{ns}/{id}/hosting supports html|files|json|kv|sites. Owner-only PATCH at the same path supports html|files|json|kv for new publications without a required subdomain. Both use X-Owner-Token and return hosting metadata with Cache-Control: no-store.

Change a new publication to Subdomain

curl -X PATCH https://brewpage.app/api/html/public/aB3xK9mP2q/hosting \
  -H "Content-Type: application/json" \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -d '{"deliveryMode":"subdomain","expectedVersion":1}'

expectedVersion = the current hostingVersion (read it with GET first). A real change increments it; a same-mode request with the current version leaves it unchanged. Switching either way retains the same host reservation and owner/content/TTL. Incorrect owner proof returns 403 OWNER_AUTHORIZATION_FAILED; an unknown mode or a malformed version (not a positive integer) returns 400; unavailable publications return 404. While new hosting is paused, real changes return 503 HOSTING_CREATION_PAUSED with Retry-After: 1; current-version no-ops still succeed.

Subdomain hosts serve publication content only, with no platform API. HTML pages and site HTML documents run natively (scripts, modules, forms, navigation; no sandbox, no rewriting) and carry the small BrewPage attribution badge; nothing else is injected. Page code must not hide or alter the badge; a profile can turn it off. Files, JSON and KV are never modified. For Markdown, code/text, files, JSON and KV a browser document navigation to the subdomain returns the BrewPage viewer; any other request receives the stored bytes as before. One dedicated host serves the entire new site bundle, including every page and asset; it is not shared across a user's sites. Sites retain native assets, directory indexes and multipage links; missing paths return 404, without SPA fallback. New subdomain short URLs redirect to the returned host; active API documents use safe attachment disposition. New p query parameters do not authenticate and are removed before trusted unlock. BrewPage-mode HTML uses stricter script, cookie, embed and navigation restrictions. See hosting and password limits before choosing a mode.

Revoke existing browser reader access with owner-only POST /api/{type}/{ns}/{id}/access/revoke, using X-Owner-Token. Supported types: html|files|json|kv|sites. Protected new publications return 200 {"revoked":true}; readers must unlock again. Content, password, host and hosting version stay unchanged, and other publications' grants remain usable. Legacy or unprotected publications return 400 ACCESS_REVOKE_UNAVAILABLE; incorrect owner proof returns 403. This cannot erase previously downloaded or offline content.

Custom domain

A custom domain is a hostname you already own and can edit DNS for, at any level (example.com, docs.example.com), that shows one publication: an HTML page of format html or a site, without a password. BrewPage does not sell domains: buy one at any registrar first (e.g. Cloudflare, Porkbun). Free with a profile: up to 5 custom domains. The publication keeps its BrewPage link; https://<hostname>/ serves it once status is active. People-first guide: /help#custom-domain.

Send X-Owner-Token. Two kinds of token work. A profile token is minted in the profile, with scope publish or admin; it works at once. An owner token works once it is added to the profile.

An owner token in no profile gets 403 DOMAIN_NEEDS_ACCOUNT. Sign in at account.brewpage.app/tokens, press Add existing token and paste the owner token. Then send the same request again. An admin profile token can add the owner token instead: POST /api/owner-token/bind.

Set the domain

PUT /api/publications/{type}/{ns}/{id}/domain with {"hostname":"www.example.com"}. {type} is html or site.

Connect www.example.com to a page

curl -X PUT https://brewpage.app/api/publications/html/public/aB3xK9mP2q/domain \
  -H "Content-Type: application/json" \
  -H "X-Owner-Token: $OWNER_TOKEN" \
  -d '{"hostname":"www.example.com"}'

Answer: 201

{"hostname": "www.example.com", "displayHostname": "www.example.com", "apex": false,
 "status": "pending_dns", "suspended": false,
 "nextStep": "Create exactly the DNS records in records[] at the DNS provider of www.example.com (...). Then call
              POST /api/publications/html/public/aB3xK9mP2q/domain/check once and read GET ... until status is active, ...",
 "records": [{"type": "TXT", "name": "_brewpage.www.example.com", "host": "_brewpage.www",
              "value": "bp-verify=<verify-token>", "state": "unknown"},
             {"type": "CNAME", "name": "www.example.com", "host": "www",
              "value": "domains.brewpage.app", "state": "unknown"}],
 "attachedTo": {"type": "html", "namespace": "public", "id": "aB3xK9mP2q",
                "link": "https://<label>.brewpage.app/", "title": "My page"},
 "serving": false, "nextCheckAt": "2026-11-12T10:15:00Z", "createdAt": "2026-11-12T10:00:00Z",
 "deliveryModeChanged": true}

Answer fields: hostname, displayHostname, apex, status, suspended, problem (absent when nothing blocks), nextStep, records[] {type, name, host, value, state, optional}, provider, attachedTo, serving, url, checkedAt, nextCheckAt, graceEndsAt, createdAt. A record's state is ok, missing, wrong, foreign, blocked or unknown. nextStep (always present) says what to do now in plain words, with this domain's exact routes: follow it and relay it to the user.

apex is true when the hostname is the domain itself (example.com). Its records are the TXT and an A record. The optional ALIAS record can replace the A record. An A record may come without value for a few minutes: read the domain again.

PUT answers also carry deliveryModeChanged: true when a page on a brewpage.app path address moved to its own subdomain. detached names the custom domain that was on this publication before; it stays in the profile.

Routes

RequestDoes
PUT /api/publications/{type}/{ns}/{id}/domainConnects the hostname, or moves a custom domain of the profile here; 201 added, 200 moved or unchanged
GET /api/publications/{type}/{ns}/{id}/domainCurrent state; 404 DOMAIN_NOT_FOUND when none
POST /api/publications/{type}/{ns}/{id}/domain/checkChecks DNS now and returns the updated state
DELETE /api/publications/{type}/{ns}/{id}/domainRemoves it from the profile; the slot is free at once; 204
GET /api/domainsLists the profile's custom domains: {limit, used, items}
POST /api/domains{"hostname":"www.example.com"}: adds a custom domain without a publication
GET /api/domains/{hostname}Reads one custom domain
POST /api/domains/{hostname}/checkChecks DNS now
DELETE /api/domains/{hostname}Removes it from the profile
PUT /api/domains/{hostname}/attachment{type, ns, id}: shows that publication on it
DELETE /api/domains/{hostname}/attachmentStops showing the publication; the custom domain stays in the profile

The /api/domains routes need a profile token with scope admin.

Then

  1. Create exactly the DNS records in records[] at your DNS provider (host is the name DNS panels ask for: a panel that appends the domain gets host, never name); never values from memory. Keep existing MX (email) records; replace an A, AAAA or CNAME record at the same name. At Cloudflare set Proxy status to DNS only.
  2. After the records exist, call POST …/domain/check once.
  3. Read GET …/domain until status is active. BrewPage checks by itself (nextCheckAt; the first full check about 15 minutes after adding); usually live within 30 minutes, HTTPS is issued automatically. Check again only after changing DNS. Records still not right a week after adding: automatic checks pause (CHECK_PAUSED); POST …/domain/check resumes them.

Statuses

statusMeans
pending_dnsDNS records not seen yet: create them; problem names the missing one
verifyingDNS records found, HTTPS being issued: wait
activeLive at url (serving: true)
lostDNS records broke after going live; still served until graceEndsAt: restore them, then check

Problems and fixes

problemFix
DOMAIN_NOT_REGISTEREDThe domain does not exist yet: register it with a domain registrar, then create the records
TXT_MISSINGCreate the TXT record of records[]
TXT_WRONGA bp-verify= TXT record has another value: replace it with the one in records[]
ROUTING_MISSINGCreate the CNAME record (apex: the A or ALIAS record)
ROUTING_WRONGThe name points elsewhere: replace its A or CNAME record (Cloudflare: DNS only)
FOREIGN_AAAADelete the AAAA record listed in records[]
CAA_BLOCKSAdd the CAA record listed in records[]
DOMAIN_TAKENThis hostname is not available: use another hostname or write to info@brewpage.app
QUEUE_FULLDNS records are right, verification waits its turn: nothing to do
CERT_PENDINGHTTPS certificate on its way: nothing to do
CERT_FAILEDThe certificate could not be issued: check the DNS records, then check again
DNS_LOSTDNS records stayed broken past graceEndsAt, so the domain was disconnected: restore them, then check again
CHECK_PAUSEDAutomatic checks paused, records not right a week after adding: fix DNS, then check again (resumes them)
RESOLVER_UNAVAILABLEDNS did not answer: retried automatically
PUBLICATION_GONEThe publication is gone: connect the custom domain to another one
NOT_ELIGIBLE_<reason>The publication cannot take a custom domain any more: reasons as for 409 NOT_ELIGIBLE below, plus MODE (it is not on its own subdomain: set the domain on it again; that moves it there)

Set it while publishing

Send domain=www.example.com as a query parameter or form/multipart field of POST /api/html or POST /api/sites. The publication is always created. The answer carries customDomain, the same object as the PUT answer. Otherwise it carries exactly one notice that says why not.

Notices on publish

NoticeWhat to do
domain-needs-accountThe owner token is in no profile: Add existing token as above, then use the PUT route
domain-limit-reachedThe profile holds all its custom domains: remove or move one
domain-not-eligibleThe publication cannot take one; the notice says why
domain-invalidNot a usable hostname; the notice says why
domain-not-registeredThe domain is not registered yet: buy it first, then set it with the PUT route
domain-account-restrictedThis profile cannot add custom domains now
domain-profile-ambiguousThe token is in several profiles: use a profile token of the profile that should hold the domain
domain-unavailableThe notice names the next step
domain-ignoredSent on an update (HTML PUT, site republish): use the PUT route

Refusals and next steps

RefusalNext step
403 DOMAIN_NEEDS_ACCOUNTOwner token in no profile: Add existing token as above, then repeat
403 OWNER_AUTHORIZATION_FAILEDWrong owner token for this publication
403 OWNER_TOKEN_REVOKEDThe token was revoked: use another owner token or profile token
403 OWNER_TOKEN_EXPIREDThe token expired: use another owner token or profile token
403 ADMIN_TOKEN_REQUIRED/api/domains routes: use a profile token with scope admin
403 ACCOUNT_RESTRICTEDThis profile cannot add custom domains now
403 ACCOUNT_BLOCKEDThis profile cannot add custom domains
400 INVALID_HOSTNAMESend one hostname such as www.example.com; the message says what to fix
400 DOMAIN_NOT_ALLOWEDbrewpage.app addresses and some domains cannot be used: use a domain you own
400 DOMAIN_NOT_REGISTEREDThe domain isn't registered yet: buy it from a domain registrar first, then add it (just bought it? try again in a few minutes)
409 NOT_ELIGIBLEreason: OWNERSHIP (add this publication's owner token to the profile), OLD (publish it again), RETIRED (set the domain on a live publication), TYPE (HTML pages and sites only), FORMAT (publish as format html), PASSWORD (remove the password), EXPIRED (it cannot come back: attach another publication)
409 DOMAIN_LIMITThe profile holds all its custom domains (limit, used): remove or move one
409 DOMAIN_PROFILE_AMBIGUOUSThe token is in several profiles: use a profile token of the profile that should hold the domain
409 DOMAIN_SUSPENDEDBrewPage suspended this domain: write to info@brewpage.app
404 DOMAIN_NOT_FOUNDNo custom domain on this publication, or the hostname is not in this profile
404 PUBLICATION_UNAVAILABLEThe publication is missing or expired
404 FEATURE_DISABLEDCustom domains are not available right now: try later
429 DOMAIN_CHECK_TOO_SOONChecked a moment ago: wait Retry-After; meanwhile just read GET …/domain
503 DOMAIN_INTAKE_PAUSEDAdding custom domains is paused: try later
503 HOSTING_CREATION_PAUSEDAddress changes are briefly unavailable: retry after Retry-After

Move or remove

Move: PUT the same hostname on another publication of the profile (200). Remove: DELETE (204); then you may delete the DNS records. The BrewPage link keeps working in both cases. Connected hostnames appear in public HTTPS certificate logs.

Page data

Page data lets a published HTML page or site save what its visitors enter on BrewPage: game progress, form answers, guestbook messages, votes, top scores. No backend and no key in the page's code: the page loads one script and calls bp.state(). Entries show in the page's Data tab, as CSV and through the API; who reads which: 4. Who reads and writes. In the API and the config the feature is called state.

1. Say what the page saves

Publish with a state member in the JSON body of POST /api/html or PUT /api/html/{ns}/{id}, or with the form field state (a JSON string) on POST /api/sites and PUT /api/sites/{ns}/{id}. {} is enough: every list is then each visitor's own. Name a list only to change its rule:

{"collections":{
  "saves":{"mode":"private"},
  "votes":{"mode":"private","choices":{"choice":["a","b","c"]}},
  "guestbook":{"mode":"shared","maxDocsPerVisitor":5},
  "scores":{"mode":"shared","index":"score","maxDocsPerVisitor":1},
  "menu":{"mode":"shared","write":"author"}}}

A raw HTML body (Content-Type: text/html) cannot carry state: send the JSON body, or turn page data on afterwards with PATCH /api/{ns}/{id}/state (author API).

Publish a page that saves data

jq -n --rawfile html page.html \
  '{content: $html, state: {collections: {guestbook: {mode: "shared", maxDocsPerVisitor: 5}}}}' \
| curl -X POST https://brewpage.app/api/html \
  -H "Content-Type: application/json" \
  --data-binary @-

Publish a site that saves data

curl -X POST https://brewpage.app/api/sites \
  -F "archive=@site.zip" \
  -F 'state={"collections":{"guestbook":{"mode":"shared","maxDocsPerVisitor":5}}}'

A page that declares state gets its own address, https://<label>.brewpage.app: the returned link points there, with deliveryModeReason: "policy:state-declared" and the notice “Pages that save data get their own address.” Where saving works: 5. Limits. A page already published on a brewpage.app/... address gets its own address with the hosting change. A page that saves data keeps its own address: turn page data off before a hosting change back to path. Page data works on HTML pages and sites; Markdown pages never run scripts.

Updates: a PUT or site republish that carries state changes only the lists it names, and a named list keeps the rule keys the body omits; the other lists keep their rule. Without state the stored description stays; "state": null turns page data off and keeps the entries. Only PATCH /api/{ns}/{id}/state replaces the whole description (author API). A list that already holds visitors' own entries or files stays that way: a publish keeps its rule with notice state-mode-kept, PATCH answers 409 STATE_MODE_WIDENING. Use a new list name for a shared version.

KeyValuesDefault
collections Up to 32 lists. Names: a-z, 0-9, _ and -, starting with a letter, up to 32 characters. _storage is built in and cannot be declared none: every list is each visitor's own
<list>.mode private or shared private
<list>.write author, on shared lists only: visitors read, only the author writes visitors write
<list>.choices Up to 4 fields, each with up to 32 string values of 1-64 characters, counted by stats({countBy}). The value other is reserved: it counts every value outside the list none
<list>.index A top-level number field of each entry; list({order: "-index"}) sorts by it none
<list>.maxDocsPerVisitor 1 up to the page's maxDocsPerVisitor the page's value
<list>.files true: visitors upload files to this list (visitor files); not on "write": "author" lists false
maxDocBytes Largest entry, 1 KB to 64 KB 16 KB
maxDocsPerVisitor Entries per visitor, 1 to 200 20
maxBytesPerVisitor Bytes per visitor, maxDocBytes to 1 MB 32 KB

A malformed state answers 400 STATE_INVALID with a message naming the part to fix; nothing is changed. The publish response carries plain-text notices with code and message:

NoticeMessageWhat to do
state-not-declared This page wants to save data, but it doesn't say what to save yet. Publish again with state, or PATCH /api/{ns}/{id}/state with {}
state-needs-subdomain This page wants to save data, but it needs its own address. Change the hosting to subdomain
state-sdk-url Load https://brewpage.app/js/state.js. Use the absolute script URL
state-needs-html state works on HTML pages and sites only. Publish the page as HTML
state-limit-clamped Limit <name> set to <value>, the highest allowed. (or: the lowest allowed.) Nothing; the page uses the value shown
state-config-ignored Unknown state key <name> ignored. Past five keys, one summary: N more unknown state keys ignored. Check the key names against the table above
state-mode-kept List <name> stays private (visitor entries exist); use a new list name for a shared one. Use a new list name
state-files-need-profile List <name> takes visitor files once this page is in a profile; until then it keeps entries only. Add the page to your profile
state-config-adjusted For example: <name>.files has no effect on a list only the author writes; read as false. Nothing; the page uses the value named
reserved-path-skipped (sites) _bp/state/ and _bp/files/ are reserved; those files were skipped. Move those files out of the _bp folder

2. Load the script

<script src="https://brewpage.app/js/state.js"></script>

Use this absolute URL in a plain script tag before your own code: no async, no import, no ?v=. A relative /js/state.js in a site points at the site itself (notice state-sdk-url). The script is served with Cache-Control: public, max-age=300, must-revalidate and Access-Control-Allow-Origin: *, so crossorigin tags and pages with cross-origin isolation load it too. Put page code in async function start() { ... } and call start(): a top-level await or return breaks a plain script. The script sets window.bp (left alone when the page already has its own bp) and always the alias window.brewpage.

If your page has its own Content-Security-Policy or service worker, let the script and its requests through: allow https://brewpage.app in script-src and same-origin requests (connect-src 'self'), and let /_bp/ requests pass the service worker to the network, or saving stops working. For the human check, see challenge_unavailable.

CallResult
await bp.state() A State, or null where saving is not available; never rejects. Always guard it: show a short note and keep the page working
bp.state.reason null with a State; else "needs_subdomain" (a brewpage.app/... address; "unavailable" when the brewpage.app viewer shows it), "embedded" (inside a frame on another site) or "unavailable" (no state declared, cookies off, a chat preview, a sandboxed frame, another site). A file or a loopback host gets the local preview and null here. The console names the fix once; check !s, not the reason
s.local true only in the local preview (file:, localhost, 127.0.0.1, [::1], *.localhost): one visitor, kept in this browser, nothing sent. ?bp-local=owner previews the owner view, ?bp-local=off turns it off; both are ignored on a published page. Absent on a published page
s.col(name) A list handle c; a bad name throws invalid_argument
await c.get(key) The value, or null. Keys: A-Z, a-z, 0-9, _, . and -, not starting with _, up to 128 characters
await c.set(key, value) Creates or replaces the visitor's own entry; resolves {key, id, version, createdAt, updatedAt}. One thing per visitor (vote, RSVP, best score): a fixed key such as "me"
await c.add(value) A new entry under a random 16-character key; same result as set
await c.remove(key) true if the entry existed, else false
await c.list({order, limit, cursor}) An array of {key, id, value, version, mine, createdAt, updatedAt} plus .next (cursor or null). order: -createdAt (default), createdAt, updatedAt, -updatedAt, index, -index. limit: 20 by default, the most per call in 5. Limits
await c.stats({countBy}) {count, scope, by}: on a declared list scope is "all" and count covers every entry; elsewhere "own". by counts each value of a declared choices field, plus other. Totals can lag a save by a few seconds; onStats keeps them live while the tab is visible
c.onStats({countBy}, fn) Calls fn(stats) now, again right after each save or removal this page makes on the list, then with the server's totals, re-read every few seconds while the tab is visible. Use it to show a visitor's own vote at once and every visitor's votes as they come. Returns a function that stops it
c.files true while this list takes visitor files, known before any upload: show the upload control only then
await c.upload(file) Uploads a File or Blob; resolves {id, url, name, contentType, sizeBytes, createdAt}. url is a path on the page's own address: img.src = f.url. Keep f.id and f.url in an entry
await c.removeFile(id) true if the file existed, else false. The uploader removes their own files; the owner removes any
bp.text(value) A text node. Render entries with it or textContent, never innerHTML
bp.storage Works like localStorage (ready, getItem, setItem, removeItem, clear, key, length), saved as one entry per visitor. await bp.storage.ready first. mode: "server", or "local" / "memory" where saving is not available. setItem throws QuotaExceededError past the page's entry size (5. Limits)
bp.StateError Every rejection: e.code (errors), e.message (plain text you can show visitors), e.status, e.retryAfter, e.serverCode

Writes run in call order. Save on change or submit, not on every keystroke; bp.storage batches by itself. A file or a loopback host runs a local preview that does not read your state; test the published link before you share it.

3. Examples

Whole example pages and the twelve templates, line by line: guide → Quick start and guide → Templates.

4. Who reads and writes

ModeVisitors readVisitors writeGood for
private (default) Their own entries Their own entries Progress, drafts, settings, form answers, votes
shared Every entry (mine marks their own) Their own entries Guestbooks, comments, top scores
shared + "write": "author" The author's entries Nothing (mode_forbidden) Menus, schedules, content you change without republishing

Each visitor reads and writes only their own entries unless a list is shared; you, the author, read them all. Lists the page uses without naming them are each visitor's own.

Owner view on the page. The owner is the browser where the page shows its owner gear: there s.role is "owner", c.list({all: true}) returns every visitor's entries (each with a visitor label, null on author API entries), one page at a time like list (pass .next as cursor for more), and c.removeById(entry.id) deletes any entry of that list. Everyone else, and everyone on a connected domain or in a frame, gets "visitor", the normal list and not_owner; s.onRole(fn) calls fn(role) now and on every change. Do not put secrets in the page: everyone can read its code, and owner-only data comes from the server.

const s = await bp.state(); if (!s) return showNote(OFF);
s.onRole(async (role) => {
  ownerBox.hidden = role !== "owner";
  if (role !== "owner") return;
  let cursor = null;
  do {
    const page = await s.col("guestbook").list({ all: true, limit: 100, cursor });
    for (const d of page) addRow(d, () => s.col("guestbook").removeById(d.id));
    cursor = page.next;
  } while (cursor);
});

5. Limits

  • Entries are JSON: text and numbers. 16 KB per entry by default (maxDocBytes, up to 64 KB); bp.storage holds one entry of that size, use lists for more.
  • Per visitor: 20 entries and 32 KB by default (up to 200 entries and 1 MB).
  • Per page: 1 MB and 5,000 entries; 10 MB and 20,000 entries for a page in a profile.
  • Visitor files: up to 5 MB per file; per visitor 20 files and 20 MB; per page 200 files and 20 MB, or 2,000 files and 200 MB for a page in a profile.
  • list() returns up to 100 entries per call; page through with cursor.
  • Entries and files live as long as the page and are deleted with it.
  • A visitor is one browser on one address, remembered by a cookie: another browser, another device or cleared cookies start as a new visitor. If the page's address changes, visitors start fresh there; their entries stay.
  • With cookies off in the browser, saves reject unavailable while reads go on; bp.storage keeps working on the device.
  • Saving needs a declared state and works only on the page's own address and its connected domain (a visitor on both is two visitors); not on a brewpage.app/... address and not when another site shows the page in a frame (embedded). Share the link instead of embedding the page.
  • bp.storage in two tabs of one page: the tab that is hidden or closed last writes the whole map; a tab still open puts its own changed keys back at its next save.
  • Scores and votes come from the visitor's browser: fine for fun, one vote per browser.
  • Never ask visitors for passwords, card numbers or other credentials.

6. Errors

Every SDK rejection is a bp.StateError. e.message is plain visitor text, so note.textContent = e.message is always safe to show.

e.codeWhat to do
unavailableShow your note; the page keeps working. bp.state.reason and the console name the fix
rate_limitedWait e.retryAfter seconds, then save again; save on change or submit, not per keystroke
quotaNo room left: offer to remove an older entry; the author frees space in the Data tab
too_largeShorten or split the value, or raise maxDocBytes; for a file, pick a smaller one
file_typeUpload one of the file types this list takes
value_refusedShared lists take text and numbers: link to files instead of embedding them. For a file, show e.message
mode_forbiddenRemove the write from the page; the author writes this list through the author API. For upload: the list takes no files, check c.files first
challenge_cancelledThe visitor closed the human check: let them save again when ready
challenge_failedLet the visitor try again
challenge_unavailableIf your page sets a Content-Security-Policy, allow https://challenges.cloudflare.com in script-src and frame-src, and on a connected domain also https://check.brewpage.app in frame-src; else ask the visitor to reload
not_foundRarely seen: get gives null and remove gives false for a missing entry
not_ownerOnly the page's owner can do this: show the control only when s.role === "owner"
invalid_argumentFix the list name, entry name or option the message names
networkOffline or no answer: try again later
errorShow the message and let the visitor try again

BrewPage may ask a visitor for a quick human check before saving; the SDK shows it and retries.

7. Visitor files

A list with "files": true takes files from visitors: a photo, a résumé, a CSV. Show the upload control when c.files is true, upload, then keep the file in an entry:

const photos = s.col("photos"); // state: {"collections":{"photos":{"files":true}}}
picker.hidden = !photos.files;
const f = await photos.upload(picker.files[0]);
await photos.add({ fileId: f.id, url: f.url, name: f.name });
img.src = f.url;
  • Types: JPEG, PNG, GIF, WebP, plain text, CSV and JSON; PDF in private lists only. The browser sends JPEG and PNG as WebP, at most 2048 px on the longer side, when that is smaller.
  • Sizes: 5. Limits.
  • A private list takes files on any page, a shared list on a page in a profile (until then the notice state-files-need-profile, and c.files is false).
  • Who opens a file: in a shared list everyone on the page; in a private list the visitor who uploaded it and you, the author. A url works on the page's own address and its connected domain.
  • Deleting an entry keeps its file: call c.removeFile(f.id) as well. Deleting a list's entries by time, in the Data tab or the author API, removes its files of that time too.
  • File names come from visitors: show them with bp.text(). The local preview keeps files in memory until a reload.

8. Author API and the Data tab

Open the page from your Publications or its management link, then the Data tab: entries and files, Download CSV, delete one entry, one file or entries and files by date, and Turn on page data for a page that does not save data yet. The author API takes X-Owner-Token or X-Manage-Key; every answer is no-store. Through the MCP server an assistant turns page data on with state on publish_html, and reads, writes, configures and deletes entries with get_page_data, set_page_data, configure_page_data and delete_page_data, using the owner token or the management link as manageUrl; after publishing it gives you the page link and the management link (private: its holder can edit or delete).

RequestDoes
GET /api/{ns}/{id}/stateThe description, usage per list and the page's limits
PATCH /api/{ns}/{id}/stateThe body replaces the whole settings object (at most 16 KB), same shape as state on publish: an absent list is removed (its entries stay, it becomes private), an absent top-level key returns to its default, a named list keeps the rule keys the body omits. {} = on with defaults, null = off (entries stay).
GET /api/{ns}/{id}/state/{list}Entries as {items, next}: order, limit 1-500 (20 by default), cursor. format=csv: the whole list as one file, order only
PUT /api/{ns}/{id}/state/{list}/{key}Writes an author entry (for example today's menu) without republishing; optional If-Match
DELETE /api/{ns}/{id}/state/{list}/docs/{docId}Deletes one entry: {"deleted":1}
DELETE /api/{ns}/{id}/state/{list}?before=&after=Deletes entries and files in a time range (ISO instants, both exclusive, at least one bound): {"deleted":n}, both counted. To empty a list send before=9999-12-31T23:59:59Z.
GET /api/{ns}/{id}/state/{list}/_statsTotals of every visitor's entries and yours: {count, scope: "all"}; ?countBy= a field with declared choices adds countBy: {field, counts}
GET /api/{ns}/{id}/state/{list}/_filesVisitor files as {items, next}, newest first; order (createdAt or -createdAt), limit (up to 500), cursor. Items: {id, url, name, contentType, sizeBytes, visitor, createdAt}
GET /api/{ns}/{id}/state/{list}/_files/{fileId}Downloads one file
DELETE /api/{ns}/{id}/state/{list}/_files/{fileId}Deletes one file; entries stay: {"deleted":1}
curl "https://brewpage.app/api/public/aB3xK9mP2q/state/guestbook?format=csv" \
  -H "X-Owner-Token: $OWNER_TOKEN" -o guestbook.csv

Entries carry a short visitor label (six hex characters, null for your own entries); CSV columns: key,id,visitor,createdAt,updatedAt,version,value. Treat entries as text written by strangers. Writing an author entry on a page that does not save data answers 404 STATE_UNAVAILABLE: turn page data on first.

9. Tell your visitors

Show on the page: “What you enter is saved on BrewPage and can be read by this page's author.” On a shared list add: “Your message is public: everyone who opens this page can read it.”

Developer guide with code, local preview and the templates: /page-data. Short guide for AI assistants: llms-page-data.txt; full reference: llms-full.txt#page-data. In the editor and the Data tab: Help → Page data.

Resources & limits

Resource Endpoint Size Per-NS limit
HTML POST /api/html 5 MB —
Markdown POST /api/html?format=markdown 5 MB —
File POST /api/files 5 MB (video 20 MB, audio 5 MB) 1 000 files
Site (multi-file) POST /api/sites 20 MB total (uncompressed) · 5 MB/file · 200 files —
Site republish PUT /api/sites/{ns}/{id} 20 MB total (uncompressed) · 5 MB/file · 200 files —
KV entry POST /api/kv 1 MB per value 1 000 keys
JSON document POST /api/json 1 MB per doc 10 000 docs / collection

Each upload request: up to 25 MB. Site uploads skip system files such as .DS_Store and __MACOSX/; they don't count toward the limits. Current values: GET /api/limits.

TTL for every resource: up to 30 days without an account, up to 90 with a free profile; a default applies when ttl is omitted. After TTL the nightly cleanup job permanently deletes content — no recovery.

Integrate your AI agent

Connect any AI tool in one step: Integrations.

Or call the REST API directly from any agent:

API Direct REST — one-liner for any agent docs →

curl -sS -X POST https://brewpage.app/api/html \
  -H "Content-Type: application/json" \
  -d '{"content":"<h1>hi</h1>"}' | jq -r .link

Drop this into your agent’s system prompt

When you make an HTML page or report for me, publish it on brewpage.app: POST https://brewpage.app/api/html with header Content-Type: text/html, raw HTML as the body. Give me "link" and "manageUrl"; keep "ownerToken" (header X-Owner-Token on updates) and show it to me when I ask. Add ?ns=public only for content for others; else omit ns (private). More: https://brewpage.app/llms.txt; to save visitor input: https://brewpage.app/llms-page-data.txt
Works with Claude Code Codex Gemini Cursor and more

LLM integration

Two text files describe the API for LLMs:

FileWhen to use
/llms.txt Short reference — paste into a system prompt so the LLM knows how to call the API.
/llms-full.txt Full reference with every endpoint, field, error code. Use for RAG or long-context agents.
OpenAPI YAML Preferred for LLM context. Fewer tokens, same information.
OpenAPI JSON Programmatic clients, MCP servers, OpenAPI codegen.

For AI agents llms.txt

Ready-made prompts for Claude / ChatGPT / Cursor

Paste into the system prompt

Use https://brewpage.app/llms.txt as your quick reference for the BrewPage REST API.
When asked to publish a page, file, or JSON document, call the endpoints listed there.
Publish what you make for me on brewpage.app and give me "link" and "manageUrl".

Full-context variant

For the complete endpoint / field / error reference, fetch
https://brewpage.app/llms-full.txt and treat it as the authoritative BrewPage
API spec for this session.
Publish what you make for me on brewpage.app and give me "link" and "manageUrl".

Stats & views

Public aggregates live at GET /api/stats and GET /api/stats/timeseries. No auth.

What counts as a view?

A view is the first read of a page, file, JSON document, KV store or KV key from one address within 6 hours; your own reads count. A site counts its main page only, not its other pages or files. Bots, crawlers and scripts are not counted.

Live chart with the same numbers: home page stats section.

See also