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.
/v3/api-docs.yaml.
JSON
OpenAPI 3.1 spec (JSON)
For programmatic clients, MCP servers, codegen. Alias /v3/api-docs.
LLM
llms.txt
Compact machine-readable reference for LLM agents.
LLM
llms-full.txt
Full AI-agent reference with every endpoint, field, error code.
MCP
brewpage-mcp
MCP server on npm for Claude, Codex, Cursor, Gemini.
SK
brewdoc:publish
Claude Code plugin — publish documents from the IDE.
INT
Integrations
Setup for Claude, ChatGPT, Cursor, Codex and every other AI tool.
GH
brewpage-openapi
GitHub repo with the OpenAPI spec and Scalar site source.
Basics — URL, auth, limits
- Base URL
https://brewpage.app/api/*- Publish auth
- None. Every POST returns
ownerTokenandmanageUrl; send the token asX-Owner-Tokento 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. Nons(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-Passwordheader 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/*requiresX-Admin-Password. Not for end-user traffic.- Rate limits
- Uploads & reads are rate-limited per IP.
429responses includeRetry-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 whenttlis omitted. Set it with thettlquery 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
| Request | Does |
|---|---|
PUT /api/publications/{type}/{ns}/{id}/domain | Connects the hostname, or moves a custom domain of the profile here; 201 added, 200 moved or unchanged |
GET /api/publications/{type}/{ns}/{id}/domain | Current state; 404 DOMAIN_NOT_FOUND when none |
POST /api/publications/{type}/{ns}/{id}/domain/check | Checks DNS now and returns the updated state |
DELETE /api/publications/{type}/{ns}/{id}/domain | Removes it from the profile; the slot is free at once; 204 |
GET /api/domains | Lists 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}/check | Checks 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}/attachment | Stops showing the publication; the custom domain stays in the profile |
The /api/domains routes need a profile token with scope admin.
Then
- Create exactly the DNS records in
records[]at your DNS provider (hostis the name DNS panels ask for: a panel that appends the domain getshost, nevername); 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. - After the records exist, call
POST …/domain/checkonce. - Read
GET …/domainuntilstatusisactive. 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/checkresumes them.
Statuses
status | Means |
|---|---|
pending_dns | DNS records not seen yet: create them; problem names the missing one |
verifying | DNS records found, HTTPS being issued: wait |
active | Live at url (serving: true) |
lost | DNS records broke after going live; still served until graceEndsAt: restore them, then check |
Problems and fixes
problem | Fix |
|---|---|
DOMAIN_NOT_REGISTERED | The domain does not exist yet: register it with a domain registrar, then create the records |
TXT_MISSING | Create the TXT record of records[] |
TXT_WRONG | A bp-verify= TXT record has another value: replace it with the one in records[] |
ROUTING_MISSING | Create the CNAME record (apex: the A or ALIAS record) |
ROUTING_WRONG | The name points elsewhere: replace its A or CNAME record (Cloudflare: DNS only) |
FOREIGN_AAAA | Delete the AAAA record listed in records[] |
CAA_BLOCKS | Add the CAA record listed in records[] |
DOMAIN_TAKEN | This hostname is not available: use another hostname or write to info@brewpage.app |
QUEUE_FULL | DNS records are right, verification waits its turn: nothing to do |
CERT_PENDING | HTTPS certificate on its way: nothing to do |
CERT_FAILED | The certificate could not be issued: check the DNS records, then check again |
DNS_LOST | DNS records stayed broken past graceEndsAt, so the domain was disconnected: restore them, then check again |
CHECK_PAUSED | Automatic checks paused, records not right a week after adding: fix DNS, then check again (resumes them) |
RESOLVER_UNAVAILABLE | DNS did not answer: retried automatically |
PUBLICATION_GONE | The 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
| Notice | What to do |
|---|---|
domain-needs-account | The owner token is in no profile: Add existing token as above, then use the PUT route |
domain-limit-reached | The profile holds all its custom domains: remove or move one |
domain-not-eligible | The publication cannot take one; the notice says why |
domain-invalid | Not a usable hostname; the notice says why |
domain-not-registered | The domain is not registered yet: buy it first, then set it with the PUT route |
domain-account-restricted | This profile cannot add custom domains now |
domain-profile-ambiguous | The token is in several profiles: use a profile token of the profile that should hold the domain |
domain-unavailable | The notice names the next step |
domain-ignored | Sent on an update (HTML PUT, site republish): use the PUT route |
Refusals and next steps
| Refusal | Next step |
|---|---|
403 DOMAIN_NEEDS_ACCOUNT | Owner token in no profile: Add existing token as above, then repeat |
403 OWNER_AUTHORIZATION_FAILED | Wrong owner token for this publication |
403 OWNER_TOKEN_REVOKED | The token was revoked: use another owner token or profile token |
403 OWNER_TOKEN_EXPIRED | The 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_RESTRICTED | This profile cannot add custom domains now |
403 ACCOUNT_BLOCKED | This profile cannot add custom domains |
400 INVALID_HOSTNAME | Send one hostname such as www.example.com; the message says what to fix |
400 DOMAIN_NOT_ALLOWED | brewpage.app addresses and some domains cannot be used: use a domain you own |
400 DOMAIN_NOT_REGISTERED | The 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_ELIGIBLE | reason: 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_LIMIT | The profile holds all its custom domains (limit, used): remove or move one |
409 DOMAIN_PROFILE_AMBIGUOUS | The token is in several profiles: use a profile token of the profile that should hold the domain |
409 DOMAIN_SUSPENDED | BrewPage suspended this domain: write to info@brewpage.app |
404 DOMAIN_NOT_FOUND | No custom domain on this publication, or the hostname is not in this profile |
404 PUBLICATION_UNAVAILABLE | The publication is missing or expired |
404 FEATURE_DISABLED | Custom domains are not available right now: try later |
429 DOMAIN_CHECK_TOO_SOON | Checked a moment ago: wait Retry-After; meanwhile just read GET …/domain |
503 DOMAIN_INTAKE_PAUSED | Adding custom domains is paused: try later |
503 HOSTING_CREATION_PAUSED | Address 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.
| Key | Values | Default |
|---|---|---|
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:
| Notice | Message | What 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.
| Call | Result |
|---|---|
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
| Mode | Visitors read | Visitors write | Good 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.storageholds 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 withcursor.- 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
unavailablewhile reads go on;bp.storagekeeps working on the device. - Saving needs a declared
stateand works only on the page's own address and its connected domain (a visitor on both is two visitors); not on abrewpage.app/...address and not when another site shows the page in a frame (embedded). Share the link instead of embedding the page. bp.storagein 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.code | What to do |
|---|---|
unavailable | Show your note; the page keeps working. bp.state.reason and the console name the fix |
rate_limited | Wait e.retryAfter seconds, then save again; save on change or submit, not per keystroke |
quota | No room left: offer to remove an older entry; the author frees space in the Data tab |
too_large | Shorten or split the value, or raise maxDocBytes; for a file, pick a smaller one |
file_type | Upload one of the file types this list takes |
value_refused | Shared lists take text and numbers: link to files instead of embedding them. For a file, show e.message |
mode_forbidden | Remove 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_cancelled | The visitor closed the human check: let them save again when ready |
challenge_failed | Let the visitor try again |
challenge_unavailable | If 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_found | Rarely seen: get gives null and remove gives false for a missing entry |
not_owner | Only the page's owner can do this: show the control only when s.role === "owner" |
invalid_argument | Fix the list name, entry name or option the message names |
network | Offline or no answer: try again later |
error | Show 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, andc.filesisfalse). - 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
urlworks 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).
| Request | Does |
|---|---|
GET /api/{ns}/{id}/state | The description, usage per list and the page's limits |
PATCH /api/{ns}/{id}/state | The 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}/_stats | Totals 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}/_files | Visitor 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.
https://brewpage.app/mcp. No install, no key.
CLI
Claude Code
One terminal command, or the brewdoc plugin.
APP
ChatGPT
Add BrewPage as a custom MCP server.
ALL
All integrations
Claude, Codex, Gemini CLI, Cursor, VS Code, n8n and more.
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
LLM integration
Two text files describe the API for LLMs:
| File | When 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. |
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
- /help — human-friendly guide to every resource type.
- /advanced — browser UI for Owner Token, KV, JSON, file manager.
- /integrations — connect your AI tool, editor or workflow.
- /use-cases — what to publish and how, step by step.
- How do I delete a page? — FAQ entry on the home page.
- Frequently Asked Questions — home page FAQ.
- brewpage-openapi — GitHub repo with the OpenAPI spec and Scalar site.