{"openapi":"3.1.0","info":{"title":"BrewPage API","description":"Free instant hosting for HTML, Markdown, JSON, key-value stores, files and sites. Send ns=public to be found: gallery + Google, Bing & AI search. Omitted ns: private (MCP: a generated private namespace). Password or hidden: unlisted. A private link is not a lock: anyone with it can open it; add a password to restrict. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password. Retain returned links. Save ownerToken privately; send it as X-Owner-Token on later publishes and updates. manageUrl is private: give it only to the owner, never publish it. How BrewPage compares with GitHub Pages, GitHub Gist, Netlify Drop, Cloudflare Drop, Tiiny Host and Static.app: https://brewpage.app/compare. Agents: remote MCP at https://brewpage.app/mcp (no auth).","termsOfService":"https://brewpage.app/terms","contact":{"name":"BrewPage","url":"https://brewpage.app"},"license":{"name":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"},"version":"2.8.59"},"externalDocs":{"description":"BrewPage API documentation (Scalar)","url":"https://kochetkov-ma.github.io/brewpage-openapi/"},"servers":[{"url":"https://brewpage.app","description":"Generated server url"}],"tags":[{"name":"KV","description":"Key-Value store with up to 1000 keys per store"},{"name":"Owner Token","description":"Get a new owner token (stateless); with an admin token, manage profile tokens."},{"name":"Gallery","description":"Browse public content from the 'public' namespace without password protection; mine=true lists the caller's own publications"},{"name":"Short Links","description":"Short URL resolver for sharing"},{"name":"Owner Check","description":"Lightweight owner-token probe; never increments views or returns content"},{"name":"HTML","description":"HTML page hosting with markdown support"},{"name":"Limits","description":"User-facing upload limits: one source for the UI, agents and docs"},{"name":"Sites","description":"Multi-file HTML site hosting via ZIP or folder upload"},{"name":"Publications","description":"Owner list and stats"},{"name":"preview","description":"Social previews: per-content OpenGraph image (1200×630 JPEG; .png is a legacy URL alias) and OG meta stub for social bots"},{"name":"SEO","description":"Search engine optimization endpoints"},{"name":"JSON","description":"JSON document store with up to 10,000 docs per collection"},{"name":"Stats","description":"Platform-wide usage statistics"},{"name":"Namespace","description":"Fresh, collision-free namespace suggestions"},{"name":"Files","description":"File hosting up to 5 MB per file (video 20 MB), 1000 files per namespace"},{"name":"Hosting Management","description":"Owner-only publication delivery settings"},{"name":"Reports","description":"Abuse reports for hosted content"}],"paths":{"/api/sites/{ns}/{id}":{"get":{"tags":["Sites"],"summary":"Get site info","description":"Returns site metadata and file list. Requires owner token","operationId":"getSiteInfo","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this site"}],"responses":{"200":{"description":"Site info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteInfoResponse"}}}},"403":{"description":"Missing or wrong owner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Site not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]},{"ManageKey":[]}]},"put":{"tags":["Sites"],"summary":"Update site","description":"Replaces the multi-file site bundle (ZIP archive or individual files with paths). Requires the owner token returned at creation. Password is preserved as-is (not changed in this operation).","operationId":"republishSite","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated tags; replace the stored tags (empty clears). Omit to keep them","required":false,"schema":{"type":"string"},"example":"demo,portfolio"},{"name":"ttl","in":"query","description":"Ignored: updates keep the original expiry; a supplied value is reported in notices (ttl-ignored).","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","description":"Ignored on update: republishing keeps the address mode (reported in deliveryNotice); sites always stay on their own subdomain","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this site"},{"name":"entry","in":"query","description":"Entry HTML file path (.html or .htm). Default: index.html, else the shallowest HTML file; a missing or non-HTML entry falls back to it and is reported in notices","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","anyOf":[{"type":"object","required":["archive"]},{"type":"object","required":["files"]}],"properties":{"archive":{"type":"string","format":"binary","description":"ZIP archive; takes precedence over individual files."},"files":{"type":"array","items":{"type":"string","format":"binary"},"minItems":1},"paths":{"type":"array","description":"Optional paths aligned with files; omitted paths use original filenames.","items":{"type":"string"}}}}}},"required":true},"responses":{"200":{"description":"Site updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUpdateResponse"}}}},"400":{"description":"Invalid request, empty bundle or limits exceeded; see GET /api/limits; or PDF/Office file unreadable or password-protected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request over the per-request size, too many files and form fields, or a file path too long; see GET /api/limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing or wrong owner token, or upload refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Site not found or expired; body has createUrl: POST the content there to publish anew","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Site is no longer available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"No servable file left: every file has an unsupported or missing extension","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]},"delete":{"tags":["Sites"],"summary":"Delete site","description":"Permanently removes the site and all its files from storage","operationId":"deleteSite","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this site"}],"responses":{"204":{"description":"Site deleted"},"403":{"description":"Missing or wrong owner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Site not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/kv/{ns}/{id}/{key}":{"get":{"tags":["KV"],"summary":"Get key value","description":"Returns the value and last update timestamp for a specific key","operationId":"getKey","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password via header","required":false,"schema":{"type":"string"}},{"name":"p","in":"query","description":"Legacy-only query password; ignored for NEW publications. Programmatic access uses X-Password or the owner token.","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to bypass password protection when no password supplied","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvGetResponse"}}}},"403":{"description":"Wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Store or key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Public publication deleted or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]},{"Password":[]}]},"put":{"tags":["KV"],"summary":"Upsert key","description":"Creates or updates a key in the store; max 1000 keys per store","operationId":"upsertKey","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this store"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvUpsertKeyRequest"}}},"required":true},"responses":{"200":{"description":"Key upserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvUpsertKeyResponse"}}}},"400":{"description":"Invalid key or value; key name `hosting` is reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing or wrong owner token or management key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Store not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Key limit exceeded, or old publication is read-only (code: OLD_PUBLICATION_READ_ONLY; publish anew via createUrl)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]},"delete":{"tags":["KV"],"summary":"Delete key","description":"Removes a single key from the store; deleting the last key removes the store","operationId":"deleteKey","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this store"}],"responses":{"204":{"description":"Key deleted"},"403":{"description":"Missing or wrong owner token or management key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Store or key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/json/{ns}/{id}":{"get":{"tags":["JSON"],"summary":"Get JSON document","description":"Returns raw JSON content with application/json content type","operationId":"getById","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password via header","required":false,"schema":{"type":"string"}},{"name":"p","in":"query","description":"Legacy-only query password; ignored for NEW publications. Programmatic access uses X-Password or the owner token.","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to bypass password protection when no password supplied","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"JSON content","content":{"application/json":{"schema":{}}}},"403":{"description":"Wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Public publication deleted or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]},{"Password":[]}]},"put":{"tags":["JSON"],"summary":"Update JSON document","description":"Replaces document content; requires the owner token returned at creation or the management key","operationId":"update","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","description":"Ignored on update: republishing keeps the address mode (reported in deliveryNotice); change it with the hosting operation","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this document"}],"requestBody":{"content":{"application/json":{"schema":{}}},"required":true},"responses":{"200":{"description":"Document updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonUpdateResponse"}}}},"403":{"description":"Missing or wrong owner token or management key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found or expired; body has createUrl: POST the content there to publish anew","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]},"delete":{"tags":["JSON"],"summary":"Delete JSON document","description":"Permanently removes the document","operationId":"delete","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this document"}],"responses":{"204":{"description":"Document deleted"},"403":{"description":"Missing or wrong owner token or management key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Document not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/html/{ns}/{id}":{"get":{"tags":["HTML"],"summary":"Get HTML page","description":"Returns rendered HTML content. Protected OLD pages accept X-Password or ?p=; NEW pages use X-Password or a reader access cookie. The owner token bypasses password protection when no password is supplied.","operationId":"getById_1","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password via header","required":false,"schema":{"type":"string"}},{"name":"p","in":"query","description":"Legacy-only query password; ignored for NEW publications. Programmatic access uses X-Password or the owner token.","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to bypass password protection when no password supplied","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"HTML content","content":{"text/html":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"text/tab-separated-values":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/xml":{"schema":{"type":"string"}}}},"403":{"description":"Wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Page not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Public publication deleted or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]},{"Password":[]}]},"put":{"tags":["HTML"],"summary":"Update HTML page","description":"Replaces page content; requires the owner token returned at creation or the management key. Also accepts raw text/* (HTML, Markdown, YAML, XML, CSV, code) bodies — see /llms-full.txt.","operationId":"update_1","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","description":"Optional new content format on republish. Accepts 'html', 'markdown'/'md', or any code format (yaml, json, xml, csv, tsv, log, toml, ini, sql, sh, bat, env, javascript, typescript, tsx, jsx, css, properties, docker, txt). When omitted, the row's stored format is preserved. Body field 'format' on HtmlUpdateRequest takes precedence over the query param when both are present.","required":false,"schema":{"type":"string"}},{"name":"tags","in":"query","description":"Comma-separated tags; replace the stored tags (empty clears). Omit to keep them","required":false,"schema":{"type":"string"},"example":"demo,test"},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"},{"name":"verbatim","in":"query","description":"Store the content exactly as sent. By default a whole HTML page pasted from a chat (wrapped in a code block, surrounded by chat text, or entity-escaped) is restored and a notice is returned; 'true' keeps the text as is.","schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlUpdateRequest"}},"text/html":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"text/yaml":{"schema":{"type":"string"}},"text/css":{"schema":{"type":"string"}},"text/javascript":{"schema":{"type":"string"}},"text/x-toml":{"schema":{"type":"string"}},"text/xml":{"schema":{"type":"string"}},"application/xml":{"schema":{"type":"string"}},"application/yaml":{"schema":{"type":"string"}},"application/x-yaml":{"schema":{"type":"string"}},"application/javascript":{"schema":{"type":"string"}},"application/toml":{"schema":{"type":"string"}}},"required":true},"responses":{"200":{"description":"Page updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlUpdateResponse"}}}},"403":{"description":"Missing or wrong owner token or management key, or upload refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Page not found or expired; body has createUrl: POST the content there to publish anew","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl (API) or republishUrl (browser)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]},"delete":{"tags":["HTML"],"summary":"Delete HTML page","description":"Permanently removes page and frees the short URL","operationId":"delete_1","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"responses":{"204":{"description":"Page deleted"},"403":{"description":"Missing or wrong owner token or management key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Page not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/files/{ns}/{id}":{"get":{"tags":["Files"],"summary":"Download file","description":"Returns file inline for previewable types (images, PDF, media) or as attachment. Add ?dl=1 to force download. An HTML file published as a page in 'public' redirects to GET /api/html/public/{id}.","operationId":"download","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password via header","required":false,"schema":{"type":"string"}},{"name":"p","in":"query","description":"Legacy-only query password; ignored for NEW publications. Programmatic access uses X-Password or the owner token.","required":false,"schema":{"type":"string"}},{"name":"dl","in":"query","description":"Force download as attachment","required":false,"schema":{"type":"boolean"}},{"name":"Range","in":"header","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to bypass password protection when no password supplied","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"File content","headers":{"X-BrewPage-Notice":{"description":"Archives only: contents unverified; check before opening.","schema":{"type":"string","enum":["archive-unverified"]}}},"content":{"*/*":{"schema":{"type":"object"}}}},"308":{"description":"HTML file published as a page; Location: /api/html/public/{id} (query string kept)","content":{"*/*":{"schema":{"type":"object"}}}},"403":{"description":"Wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Public publication deleted or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]},{"Password":[]}]},"put":{"tags":["Files"],"summary":"Replace file","description":"Replaces the file content (multipart 'file'); same type rules and limits as upload. Keeps link, password, TTL and tags. For an HTML file published as a page in 'public', replaces that page (UTF-8 .html/.htm, same rules as PUT /api/html).","operationId":"replaceFile","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"ttl","in":"query","description":"Ignored: updates keep the original expiry; a supplied value is reported in notices (ttl-ignored).","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"File part; any single file part is accepted when 'file' is absent"}}}}},"required":true},"responses":{"200":{"description":"File replaced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUpdateResponse"}}}},"400":{"description":"Invalid request or file too large; or PDF/Office file unreadable or password-protected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing or wrong owner token or management key, or upload refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found or expired; body has createUrl: POST the content there to publish anew","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY; publish anew via createUrl), or the same content is another file of this owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported file type or content of no supported type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]},"delete":{"tags":["Files"],"summary":"Delete file","description":"Permanently removes the file from storage. For an HTML file published as a page in 'public', deletes that page (same owner token)","operationId":"delete_2","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{1,32}$"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"responses":{"204":{"description":"File deleted"},"403":{"description":"Missing or wrong owner token or management key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"File not found or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/{type}/{ns}/{id}/password":{"post":{"tags":["Hosting Management"],"summary":"Set, change or remove the reader password","operationId":"setPassword","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResponse"}}}},"403":{"description":"Missing or wrong owner token or management key; token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable (outside public also for wrong credentials)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Password too short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/{type}/{ns}/{id}/visibility":{"post":{"tags":["Hosting Management"],"summary":"Hide or show a public publication in gallery & search. Link unchanged","operationId":"setVisibility","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityResponse"}}}},"403":{"description":"Missing or wrong owner token or management key; token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable (outside public also for wrong credentials)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/{type}/{ns}/{id}/rotate":{"post":{"tags":["Hosting Management"],"summary":"Change link: new id, the old link stops working","operationId":"rotatePublicationLink","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token","required":false,"schema":{"type":"string"}},{"name":"X-Manage-Key","in":"header","description":"Management key","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicationRotateResponse"}}}},"403":{"description":"Missing or wrong owner token or management key; token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable (outside public also for wrong credentials)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Link changes temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits; or ROTATE_LIMITED: at most 3 link changes a day","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/{type}/{ns}/{id}/manage-key":{"post":{"tags":["Hosting Management"],"summary":"Mint or reset the management link; the old link stops working","operationId":"resetManageKey","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManageKeyResponse"}}}},"403":{"description":"Missing or wrong owner token or management key; token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable (outside public also for wrong credentials)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/{type}/{ns}/{id}/extend":{"post":{"tags":["Hosting Management"],"summary":"Extend storage to 90 days from now (profile owners); never shortens","operationId":"extendPublication","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendResponse"}}}},"403":{"description":"Missing or wrong owner token or management key; token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable (outside public also for wrong credentials)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Old publication is read-only (code: OLD_PUBLICATION_READ_ONLY); publish anew via createUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/{type}/{ns}/{id}/access/revoke":{"post":{"tags":["Hosting Management"],"summary":"Revoke reader access to a new protected publication","operationId":"revokeReaderAccess","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessRevokeResponse"}}}},"400":{"description":"Reader access revocation requires a NEW protected publication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing or wrong owner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/api/sites":{"post":{"tags":["Sites"],"summary":"Upload site","description":"Upload a multi-file HTML site as a ZIP archive or as individual files with paths. Returns a link to the published site. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password.","operationId":"uploadSite","parameters":[{"name":"ns","in":"query","description":"Send ns=public for anything meant to be found or shared (docs, guides, demos, portfolios, reports, landing pages): listed in the public gallery and sitemap, so Google, Bing and AI search index it and people discover it. A site always gets its own subdomain. Anyone can find and read a public page: never put secrets, tokens or personal data there. No ns (default): private. Unlisted and not indexed; anyone who has the link can still open it. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"tags","in":"query","description":"Comma-separated tags","required":false,"schema":{"type":"string"},"example":"demo,portfolio"},{"name":"ttl","in":"query","description":"TTL in days (1-30, up to 90 with an X-Owner-Token in a profile); omitted or blank uses 15 days. Accepts 15, 15d, 15 days; h/w/mo/y units round up to whole days. Out-of-range values are clamped and unparseable ones use the default; each adjustment is reported in notices.","required":false,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Reuse existing owner token to group entities under one owner"},{"name":"entry","in":"query","description":"Entry HTML file path (.html or .htm). Default: index.html, else the shallowest HTML file; a missing or non-HTML entry falls back to it and is reported in notices","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","anyOf":[{"type":"object","required":["archive"]},{"type":"object","required":["files"]}],"properties":{"archive":{"type":"string","format":"binary","description":"ZIP archive; takes precedence over individual files."},"files":{"type":"array","items":{"type":"string","format":"binary"},"minItems":1},"paths":{"type":"array","description":"Optional paths aligned with files; omitted paths use original filenames.","items":{"type":"string"}}}}}},"required":true},"responses":{"201":{"description":"Site uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUploadResponse"}}}},"400":{"description":"Invalid request, no HTML files, or limits exceeded; see GET /api/limits; or PDF/Office file unreadable or password-protected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request over the per-request size, too many files and form fields, or a file path too long; see GET /api/limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Upload refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"No servable file left: every file has an unsupported or missing extension","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]}},"/api/reports":{"post":{"tags":["Reports"],"summary":"Submit abuse report","description":"Records a public report about a resource hosted on brewpage.app for moderator review","operationId":"submitReport","parameters":[{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRequest"}}},"required":true},"responses":{"201":{"description":"Report accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many reports from this address today","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/owner-token/revoke":{"post":{"tags":["Owner Token"],"summary":"Delete a profile token by id or token; it stops working everywhere, its publications stay","operationId":"revokeOwnerToken","parameters":[{"name":"X-Owner-Token","in":"header","description":"Admin token of the profile","required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRequest"}}}},"responses":{"200":{"description":"Revoked (false = already revoked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeResponse"}}}},"403":{"description":"Header token not admin, not in a profile, revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not a token of this profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]}]}},"/api/owner-token/revoke-others":{"post":{"tags":["Owner Token"],"summary":"Delete every other active profile token","operationId":"revokeOtherOwnerTokens","parameters":[{"name":"X-Owner-Token","in":"header","description":"Admin token of the profile","required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeOthersRequest"}}}},"responses":{"200":{"description":"Number of tokens deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeOthersResponse"}}}},"403":{"description":"Header token not admin, not in a profile, revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]}]}},"/api/owner-token/mint":{"post":{"tags":["Owner Token"],"summary":"Mint a profile token with scope and expiry; the token is shown once","operationId":"mintOwnerToken","parameters":[{"name":"X-Owner-Token","in":"header","description":"Admin token of the profile","required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintRequest"}}}},"responses":{"201":{"description":"Minted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintResponse"}}}},"400":{"description":"Invalid label, scope or expiresIn","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Header token not admin, not in a profile, revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Active token limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]}]}},"/api/owner-token/bind":{"post":{"tags":["Owner Token"],"summary":"Add a token to your profile (as publish)","operationId":"bindOwnerToken","parameters":[{"name":"X-Owner-Token","in":"header","description":"Admin token of the profile","required":true}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindRequest"}}}},"responses":{"200":{"description":"Bound (also when already in the profile)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindResponse"}}}},"400":{"description":"Invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Header token not admin, not in a profile, revoked or expired; or body token revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Active token limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]}]}},"/api/kv":{"get":{"tags":["KV"],"summary":"List KV stores","description":"Returns all KV stores owned by the given token in the namespace. Returns empty list without token","operationId":"listStores","parameters":[{"name":"ns","in":"query","description":"Namespace. Omitted: private. `public` = gallery & search. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to filter by ownership. Without token returns empty list"}],"responses":{"200":{"description":"Store list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/KvStoreListResponse"}}}}},"403":{"description":"Owner token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]},"post":{"tags":["KV"],"summary":"Create KV store","description":"Creates a new store with an initial key-value pair and returns a shareable link. Reuse existing owner token to group entities under one owner. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password.","operationId":"createStore","parameters":[{"name":"ns","in":"query","description":"No ns (default): private. ns=public: the shared public namespace. JSON and KV are never listed in the gallery or indexed, in any namespace; anyone who has the link can open it. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"tags","in":"query","description":"Comma-separated tags","required":false,"schema":{"type":"string"},"example":"demo,test"},{"name":"ttl","in":"query","description":"TTL in days (1-30, up to 90 with an X-Owner-Token in a profile); omitted or blank uses 15 days. Accepts 15, 15d, 15 days; h/w/mo/y units round up to whole days. Out-of-range values are clamped and unparseable ones use the default; each adjustment is reported in notices.","required":false,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password; protected stores are unlisted. NEW browser links use trusted unlock; programmatic reads use X-Password","required":false,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","description":"Delivery mode for a new store: path or subdomain","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Reuse existing owner token to group entities under one owner. If omitted, a new token is generated"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvCreateStoreRequest"}}},"required":true},"responses":{"201":{"description":"Store created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KvCreateStoreResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Owner token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]}},"/api/json":{"get":{"tags":["JSON"],"summary":"List JSON documents","description":"Returns documents owned by the given token. Empty list without token","operationId":"list","parameters":[{"name":"ns","in":"query","description":"Namespace. Omitted: private. `public` = gallery & search. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to filter by ownership. Without token returns empty list"}],"responses":{"200":{"description":"Document list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JsonListResponse"}}}}},"403":{"description":"Owner token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]},"post":{"tags":["JSON"],"summary":"Create JSON document","description":"Stores any valid JSON and returns a shareable link. Reuse existing owner token to group entities under one owner. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password.","operationId":"create","parameters":[{"name":"ns","in":"query","description":"No ns (default): private. ns=public: the shared public namespace. JSON and KV are never listed in the gallery or indexed, in any namespace; anyone who has the link can open it. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"tags","in":"query","description":"Comma-separated tags","required":false,"schema":{"type":"string"},"example":"demo,test"},{"name":"ttl","in":"query","description":"TTL in days (1-30, up to 90 with an X-Owner-Token in a profile); omitted or blank uses 15 days. Accepts 15, 15d, 15 days; h/w/mo/y units round up to whole days. Out-of-range values are clamped and unparseable ones use the default; each adjustment is reported in notices.","required":false,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password; protected documents are unlisted. NEW browser links use trusted unlock; programmatic reads accept X-Password","required":false,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","description":"Delivery mode for a new document: path or subdomain","required":false,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Reuse existing owner token to group entities under one owner. If omitted, a new token is generated"}],"requestBody":{"content":{"application/json":{"schema":{}}},"required":true},"responses":{"201":{"description":"Document created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonCreateResponse"}}}},"400":{"description":"Invalid JSON or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Owner token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]}},"/api/html":{"post":{"tags":["HTML"],"summary":"Create HTML page","description":"Stores HTML or markdown content and returns a shareable link. Reuse existing owner token to group entities under one owner. Also accepts raw text/* (HTML, Markdown, YAML, XML, CSV, code) and application/octet-stream bodies — see /llms-full.txt. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password.","operationId":"create_1","parameters":[{"name":"ns","in":"query","description":"Send ns=public for anything meant to be found or shared (docs, guides, demos, portfolios, reports, landing pages): listed in the public gallery and sitemap, so Google, Bing and AI search index it and people discover it. Public pages are served on the brewpage.app domain itself, for the strongest search reach; code that needs its own origin (cookies, storage) gets its own subdomain automatically. Anyone can find and read a public page: never put secrets, tokens or personal data there. No ns (default): private. Unlisted and not indexed; anyone who has the link can still open it. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"tags","in":"query","description":"Comma-separated tags","required":false,"schema":{"type":"string"},"example":"demo,test"},{"name":"ttl","in":"query","description":"TTL in days (1-30, up to 90 with an X-Owner-Token in a profile); omitted or blank uses 15 days. Accepts 15, 15d, 15 days; h/w/mo/y units round up to whole days. Out-of-range values are clamped and unparseable ones use the default; each adjustment is reported in notices.","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","description":"Content format. 'html' (default) — stored as sent, except a whole page pasted from a chat is repaired (see 'verbatim'); omitted, source code or JSON is saved as its code format (notice format-detected). 'markdown' / 'md' — rendered to styled HTML via github-markdown-css. Code/text languages stored and served raw with format-specific MIME (text/csv, application/json, text/plain) plus X-Content-Type-Options: nosniff; raw reads of xml answer text/plain, downloads keep text/xml: yaml, json, xml, csv, tsv, log, toml, ini, sql, sh, bat, env, javascript, typescript, tsx, jsx, css, properties, docker, txt","required":false,"schema":{"type":"string","default":"html"}},{"name":"X-Password","in":"header","description":"Access password. Empty means no password restriction. Protected pages are never listed in the gallery or sitemap. OLD links accept ?p=; NEW access uses X-Password or a reader access cookie after password entry.","required":false,"schema":{"type":"string"}},{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},{"name":"verbatim","in":"query","description":"Store the content exactly as sent. By default a whole HTML page pasted from a chat (wrapped in a code block, surrounded by chat text, or entity-escaped) is restored and a notice is returned; 'true' keeps the text as is.","schema":{"type":"boolean"}},{"name":"X-Owner-Token","in":"header","description":"Reuse existing owner token to group entities under one owner. If omitted, a new token is generated"},{"name":"X-Delivery-Mode","in":"header","description":"NEW delivery preference: path or subdomain. Sites and non-public HTML pages get subdomain; a mismatch is reported in deliveryModeReason, not rejected. Omission allows smart selection.","required":false,"schema":{"type":"string","enum":["path","subdomain"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlUploadRequest"}},"text/html":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}},"text/yaml":{"schema":{"type":"string"}},"text/css":{"schema":{"type":"string"}},"text/javascript":{"schema":{"type":"string"}},"text/x-toml":{"schema":{"type":"string"}},"text/xml":{"schema":{"type":"string"}},"application/xml":{"schema":{"type":"string"}},"application/yaml":{"schema":{"type":"string"}},"application/x-yaml":{"schema":{"type":"string"}},"application/javascript":{"schema":{"type":"string"}},"application/toml":{"schema":{"type":"string"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}},"required":true},"responses":{"201":{"description":"Page created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlUploadResponse"}}}},"400":{"description":"Invalid request parameters; or PDF/Office file unreadable or password-protected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Upload refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]}},"/api/files":{"get":{"tags":["Files"],"summary":"List files","description":"Returns files owned by the given token. Empty list without token","operationId":"list_1","parameters":[{"name":"ns","in":"query","description":"Namespace. Omitted: private. `public` = gallery & search. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"X-Owner-Token","in":"header","description":"Owner token to filter by ownership. Without token returns empty list"}],"responses":{"200":{"description":"File list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FileListResponse"}}}}},"403":{"description":"Owner token revoked or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]},"post":{"tags":["Files"],"summary":"Upload file","description":"Stores a file via multipart upload and returns a download link. Only safe file types accepted; a missing or wrong extension is corrected from the content and reported in notices. Reuse existing owner token to group entities under one owner. A UTF-8 .html/.htm file sent to namespace 'public' without a password is published as an HTML page (same rules and limits as POST /api/html): link and ownerLink point to the page, notice 'html-file-as-page'. Any other HTML file is stored as a file and shown as source, notice 'html-file-as-source'; to publish such a page use POST /api/html. Secrets allowed; likely ones are flagged in notices. For a secret: private namespace + password.","operationId":"upload","parameters":[{"name":"ns","in":"query","description":"Send ns=public for anything meant to be found or shared (docs, guides, demos, portfolios, reports, landing pages): listed in the public gallery and sitemap, so Google, Bing and AI search index it and people discover it. Public pages are served on the brewpage.app domain itself, for the strongest search reach; code that needs its own origin (cookies, storage) gets its own subdomain automatically. Anyone can find and read a public page: never put secrets, tokens or personal data there. No ns (default): private. Unlisted and not indexed; anyone who has the link can still open it. Lowercase only.","required":false,"schema":{"type":"string","pattern":"^$|^[a-z0-9-]{1,32}$"}},{"name":"tags","in":"query","description":"Comma-separated tags","required":false,"schema":{"type":"string"},"example":"demo,test"},{"name":"ttl","in":"query","description":"TTL in days (1-30, up to 90 with an X-Owner-Token in a profile); omitted or blank uses 15 days. Accepts 15, 15d, 15 days; h/w/mo/y units round up to whole days. Out-of-range values are clamped and unparseable ones use the default; each adjustment is reported in notices.","required":false,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password. Empty = public file visible in gallery. With password = hidden from gallery; readers unlock the publication or use X-Password for API access","required":false,"schema":{"type":"string"}},{"name":"X-Delivery-Mode","in":"header","required":false,"schema":{"type":"string"}},{"name":"verbatim","in":"query","description":"For an HTML file published as a page: store it exactly as sent. By default a whole HTML page pasted from a chat (wrapped in a code block, surrounded by chat text, or entity-escaped) is restored and a notice is returned; 'true' keeps the text as is.","schema":{"type":"boolean"}},{"name":"X-Owner-Token","in":"header","description":"Reuse existing owner token to group entities under one owner. If omitted, a new token is generated"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"File part; any single file part is accepted when 'file' is absent"}}}}},"required":true},"responses":{"201":{"description":"File uploaded, or HTML file published as a page. Header X-Existing-Resource: 1 when an existing publication with the same content was returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}}},"400":{"description":"Invalid request or file too large; or PDF/Office file unreadable or password-protected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Upload refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unsupported file type or content of no supported type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Busy; retry after Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{},{"OwnerToken":[]}]}},"/api/{type}/{ns}/{id}/hosting":{"get":{"tags":["Hosting Management"],"summary":"Read owner-only publication delivery settings","operationId":"getHosting","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostingReadResponse"}}}},"403":{"description":"Missing or wrong owner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Publication unavailable; owner credentials valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]},"patch":{"tags":["Hosting Management"],"summary":"Change delivery mode for a new publication. Sites and non-public HTML pages stay on subdomain; mismatches are reported, not rejected","operationId":"updateHosting","parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["html","files","json","kv","sites"]}},{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Owner-Token","in":"header","description":"Owner token returned at creation"},{"name":"X-Manage-Key","in":"header","description":"Management key of this publication"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostingUpdateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostingProjection"}}}},"400":{"description":"Unknown delivery mode or malformed expectedVersion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing or wrong owner token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Publication unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Hosting changes temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited: wait Retry-After (= retryAfterSeconds); no account: accountUrl, free sign-up with higher limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"OwnerToken":[]},{"ManageKey":[]}]}},"/{ns}/{id}":{"get":{"tags":["Short Links"],"summary":"Open short link","description":"Serves the publication behind the link: page, site, file, JSON or KV. 410 for a deleted public publication; otherwise 404.","operationId":"resolve","parameters":[{"name":"ns","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Password","in":"header","description":"Access password for protected resources","required":false,"schema":{"type":"string"}},{"name":"p","in":"query","description":"Legacy-only query password; ignored for NEW publications. Programmatic access uses X-Password or the owner token.","required":false,"schema":{"type":"string"}},{"name":"dl","in":"query","description":"Force download as attachment","required":false,"schema":{"type":"boolean"}},{"name":"raw","in":"query","description":"Bypass SPA: stream raw bytes directly (used by