openapi: 3.1.0
info:
title: BrewPage Files HTML API
description: Free instant hosting for HTML, Markdown, AI artifacts and files
version: 1.51.1
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: BrewPage Get HTML Page
description: Returns rendered HTML content; password-protected pages require X-Password header or ?p= query param
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: Access password via query param (alternative to X-Password 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: HTML content
content:
'*/*':
schema:
type: string
'403':
description: Wrong password
content:
'*/*':
schema:
type: string
'404':
description: Page not found or expired
content:
'*/*':
schema:
type: string
put:
tags:
- HTML
summary: BrewPage 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'
required: true
responses:
'200':
description: Page updated
content:
'*/*':
schema:
$ref: '#/components/schemas/HtmlUpdateResponse'
'403':
description: Missing or wrong owner token
content:
'*/*':
schema:
$ref: '#/components/schemas/HtmlUpdateResponse'
'404':
description: Page not found or expired
content:
'*/*':
schema:
$ref: '#/components/schemas/HtmlUpdateResponse'
delete:
tags:
- HTML
summary: BrewPage 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
'404':
description: Page not found or expired
/api/html:
post:
tags:
- HTML
summary: BrewPage 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_2
parameters:
- name: ns
in: query
description: 'Namespace. Default: public. Pages in ''public'' without password appear in gallery. Custom namespace is created automatically'
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: Time to live in days (1-30, default 15). Page auto-deletes after expiry. Accepts '15', '15d' or '15 days'
required: false
schema:
type: string
- 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 = public page visible in gallery. With password = hidden from gallery, viewers must enter password or pass ?p= in URL
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
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HtmlUploadRequest'
required: true
responses:
'201':
description: Page created
content:
'*/*':
schema:
$ref: '#/components/schemas/HtmlUploadResponse'
'400':
description: Invalid request parameters
content:
'*/*':
schema:
$ref: '#/components/schemas/HtmlUploadResponse'
'429':
description: Rate limit exceeded
content:
'*/*':
schema:
$ref: '#/components/schemas/HtmlUploadResponse'
/api/html/{ns}/{id}/source:
get:
tags:
- HTML
summary: BrewPage 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: getSource
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: false
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:
'*/*':
schema:
type: object
'403':
description: Wrong owner token
content:
'*/*':
schema:
type: object
'404':
description: Page not found or expired
content:
'*/*':
schema:
type: object
components:
schemas:
HtmlUploadResponse:
type: object
properties:
id:
type: string
description: Unique 10-character alphanumeric page ID
namespace:
type: string
link:
type: string
description: Public short URL for browser viewing
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
HtmlUpdateRequest:
type: object
properties:
content:
type: string
description: New HTML content to replace existing page
format:
type: string
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.
HtmlUploadRequest:
type: object
properties:
content:
type: string
description: HTML or markdown content to publish
filename:
type: string
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
description: Per-content toggle for the frontend top toolbar. null = use global default (app.ui.show-top-bar-default)
HtmlUpdateResponse:
type: object
properties:
id:
type: string
namespace:
type: string
link:
type: string
description: Public short URL for browser viewing
ownerLink:
type: string
description: API URL for programmatic access
expiresAt:
type: string
format: date-time
sizeBytes:
type: integer
format: int64