Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: BrewPage HTML API
description: Free instant hosting for HTML, Markdown, JSON, key-value stores, files and sites. REST omission defaults to the public namespace; MCP omission creates an unlisted namespace. Unlisted URLs are accessible to anyone with the link; use a password for access restrictions. Retain returned links and ownership tokens. Public discovery requires eligibility; protected and non-public publications are excluded.
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: 1.112.0
servers:
- url: https://brewpage.app
description: Generated server url
tags:
- name: HTML
description: HTML page hosting with markdown support
paths:
/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'
security:
- {}
- OwnerToken: []
- Password: []
put:
tags:
- HTML
summary: Update HTML page
description: Replaces page content; requires the owner token returned at creation. 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: X-Owner-Token
in: header
description: Owner token returned at creation. Required for update and delete
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: User-Agent
in: header
required: false
schema:
type: string
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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Page not found or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- OwnerToken: []
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. Required for update and delete
required: true
schema:
type: string
responses:
'204':
description: Page deleted
'403':
description: Missing or wrong owner token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Page not found or expired
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.
operationId: create_1
parameters:
- name: ns
in: query
description: Namespace (default public). Custom namespaces are unlisted, accessible to anyone with the URL. Public discovery additionally requires eligibility and no password.
required: false
schema:
type: string
default: public
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 integer days (1-30); accepts 15, 15d, 15 day or 15 days, case-insensitive. Omitted or blank uses 15 days.
required: false
schema:
type: string
pattern: ^\s*(?:\d+\s*(?:[dD]|[dD][aA][yY][sS]?)?)?\s*$
- name: format
in: query
description: 'Content format. ''html'' (default) — stored verbatim. ''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/xml, text/plain) plus X-Content-Type-Options: nosniff: 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; public discovery additionally requires eligibility. Protected pages are hidden from the gallery. OLD links accept ?p=; NEW access uses X-Password or a reader access cookie after password entry.
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
required: false
schema:
type: string
- name: User-Agent
in: header
required: false
schema:
type: string
- name: X-Delivery-Mode
in: header
description: 'NEW delivery preference: path or subdomain. Non-public namespaces require subdomain; 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
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- {}
- OwnerToken: []
/api/html/{ns}/{id}/source:
get:
tags:
- HTML
summary: Get HTML page raw source
description: Returns the raw user-submitted content (pre-render, pre-sanitize) plus metadata for republish. Owner-only — requires the owner token returned at creation.
operationId: getHtmlSource
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. Required for source access
required: true
schema:
type: string
responses:
'200':
description: Raw source body and metadata
content:
'*/*':
schema:
type: object
'400':
description: 'Owner token missing (code: OWNER_TOKEN_REQUIRED)'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Wrong owner token
'404':
description: 'Missing publication: empty body. An expired or unavailable NEW delivery returns the JSON ErrorResponse envelope.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- OwnerToken: []
/api/html/{ns}/{id}/settings:
get:
tags:
- HTML
summary: Get HTML page settings
description: Returns republish-prefill settings (namespace, ttlDays, hasPassword, showTopBar, format, title, filename, createdAt, expiresAt) without the content body. Owner-only — requires the owner token returned at creation.
operationId: getHtmlSettings
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. Required for settings access
required: true
schema:
type: string
responses:
'200':
description: Settings projection
content:
'*/*':
schema:
type: object
'400':
description: 'Owner token missing (code: OWNER_TOKEN_REQUIRED)'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Wrong owner token
'404':
description: 'Missing publication: empty body. An expired or unavailable NEW delivery returns the JSON ErrorResponse envelope.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- OwnerToken: []
components:
schemas:
HtmlUpdateResponse:
type: object
description: HTML update result. NEW publications include hosting metadata; OLD publications omit it.
properties:
id:
type: string
namespace:
type: string
link:
type: string
description: Primary URL returned for browser viewing and sharing
ownerLink:
type: string
description: API URL for programmatic access
expiresAt:
type: string
format: date-time
sizeBytes:
type: integer
format: int64
result:
description: 'Publication outcome envelope: code + action + optional reason.'
oneOf:
- $ref: '#/components/schemas/AbuseResult'
visibilityNotice:
type: string
description: Human-readable explanation of link access and conditional public-discovery eligibility. Unlisted links are not secret; password protection applies when configured. No guarantee of listing, ranking or search-engine indexing.
deliveryModeReason:
type: string
description: 'Set as ''advisory:<codes>'' when the updated page stays on a BrewPage link but uses browser features that may not work fully there. An update never changes the delivery mode. Codes are comma-separated in a fixed order: storage, cookies, history, downloads, top-navigation, media-capture, pointer-lock, embeds, fullscreen. Absent when nothing applies.'
deliveryNotice:
type: string
description: Human-readable explanation of deliveryModeReason. Absent whenever deliveryModeReason is absent.
managementLink:
type:
- string
- 'null'
routingCohort:
type: string
deliveryMode:
type:
- string
- 'null'
requestedDeliveryMode:
type:
- string
- 'null'
effectiveDeliveryMode:
type:
- string
- 'null'
deliveryModeMatched:
type:
- boolean
- 'null'
access:
type: string
modeLocked:
type: boolean
hostingVersion:
type:
- integer
- 'null'
format: int64
required:
- expiresAt
- id
- link
- namespace
- ownerLink
- sizeBytes
HtmlUploadRequest:
type: object
properties:
content:
type: string
description: HTML or markdown content to publish
filename:
type:
- string
- 'null'
description: Optional original filename used as the tab title fallback and download basename. Trimmed; rejected if it contains path separators or control characters, length > 200, or bare name shorter than 4 chars
showTopBar:
type:
- boolean
- 'null'
description: Per-content toggle for the frontend top toolbar. null = use global default (app.ui.show-top-bar-default)
required:
- content
ErrorResponse:
type: object
properties:
status:
type: integer
format: int32
error:
type: string
message:
type: string
timestamp:
type: string
format: date-time
supportedTypes:
type: array
items:
type: string
retryAfterSeconds:
type: integer
format: int64
limit:
type: integer
format: int32
result:
oneOf:
- $ref: '#/components/schemas/AbuseResult'
code:
type: string
required:
- error
- message
- status
- timestamp
AbuseResult:
type: object
properties:
code:
type: string
enum:
- success
- duplicate
- warned
- failed
action:
type: string
enum:
- created
- created_missing_assets
- updated
- merged
- created_warned
- unavailable
- rate_limited
- rejected
reason:
type: string
extras:
type: object
additionalProperties: {}
required:
- action
- code
HtmlUploadResponse:
type: object
properties:
id:
type: string
description: Unique 10-character alphanumeric page ID
namespace:
type: string
link:
type: string
description: Primary URL returned for browser viewing and sharing
ownerLink:
type: string
description: API URL for programmatic access (update/delete)
expiresAt:
type: string
format: date-time
sizeBytes:
type: integer
format: int64
tags:
type: array
items:
type: string
ownerToken:
type: string
description: Secret token required for update and delete operations. Store it safely -- cannot be recovered
result:
description: 'Publication outcome envelope: code (success|duplicate|warned|failed) + action (created|updated|merged|created_warned|...) + optional reason. Present on every POST/PUT response.'
oneOf:
- $ref: '#/components/schemas/AbuseResult'
visibilityNotice:
type: string
description: Human-readable explanation of link access and conditional public-discovery eligibility. Unlisted links are not secret; password protection applies when configured. No guarantee of listing, ranking or search-engine indexing.
deliveryModeReason:
type: string
description: 'Why the delivery mode was chosen or flagged. ''auto:<codes>'' -- the page was published in subdomain mode automatically because it uses browser features a BrewPage link does not provide. ''advisory:<codes>'' -- the mode was kept, but those features may not work fully on a BrewPage link. Codes are comma-separated in a fixed order: storage, cookies, history, downloads, top-navigation, media-capture, pointer-lock, embeds, fullscreen. Absent when nothing applies.'
deliveryNotice:
type: string
description: Human-readable explanation of deliveryModeReason, including how to change the delivery mode. Absent whenever deliveryModeReason is absent.
managementLink:
type:
- string
- 'null'
routingCohort:
type: string
deliveryMode:
type:
- string
- 'null'
requestedDeliveryMode:
type:
- string
- 'null'
effectiveDeliveryMode:
type:
- string
- 'null'
deliveryModeMatched:
type:
- boolean
- 'null'
access:
type: string
modeLocked:
type: boolean
hostingVersion:
type:
- integer
- 'null'
format: int64
required:
- access
- deliveryMode
- deliveryModeMatched
- effectiveDeliveryMode
- expiresAt
- hostingVersion
- id
- link
- managementLink
- modeLocked
- namespace
- ownerLink
- ownerToken
- requestedDeliveryMode
- routingCohort
- sizeBytes
- tags
HtmlUpdateRequest:
type: object
properties:
content:
type: string
description: New HTML content to replace existing page
format:
type:
- string
- 'null'
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. Takes precedence over the 'format' query param when both are present.
required:
- content
securitySchemes:
OwnerToken:
type: apiKey
name: X-Owner-Token
in: header
Password:
type: apiKey
name: X-Password
in: header
externalDocs:
description: BrewPage API documentation (Scalar)
url: https://kochetkov-ma.github.io/brewpage-openapi/
x-provenance:
method: harvested
publisher: BrewPage
source: https://brewpage.app/v3/api-docs
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)