BrewPage API — REST API Reference

API docs & tools

UI Swagger UI Interactive API browser with Try-it-out on this domain. UI Scalar reference Hosted OpenAPI browser on GitHub Pages. YAML OpenAPI 3.1 spec (YAML) Recommended for LLM context — ~25% fewer tokens than JSON. Alias /v3/api-docs.yaml. JSON OpenAPI 3.1 spec (JSON) For programmatic clients, MCP servers, codegen. Alias /v3/api-docs. LLM llms.txt Compact machine-readable reference for LLM agents. LLM llms-full.txt Full AI-agent reference with every endpoint, field, error code. MCP brewpage-mcp MCP server on npm for Claude, Codex, Cursor, Gemini. SK brewdoc:publish Claude Code skill — publish documents from the IDE. GH brewpage-openapi GitHub repo with the OpenAPI spec and Scalar site source.

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

Basics — URL, auth, limits

Base URL: https://brewpage.app/api/*
Publish auth: None. Every POST returns an ownerToken — send it as X-Owner-Token to edit or delete later.
Namespace: ?ns= query param (default public). Any non-public namespace makes the resource private (hidden from gallery, sitemap, search engines).
Password: Optional X-Password header for access-gated content. Readers send the same header or ?p=.
Admin: /api/admin/* requires X-Admin-Password. Not for end-user traffic.
Rate limits: 60 uploads / hour / IP · 300 reads / minute / IP. 429 responses include Retry-After. Details: /help#rate-limits.
User-Agent: Required on every request. Format AgentName/version.
TTL: 15 days default, 30 days max. Override with ttl query param or body field. Expired content is permanently deleted by the nightly cleanup job.

Quick start — curl

Publish HTML (public)

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

Response: {"id":"aB3xK9mP2q","namespace":"public","link":"https://brewpage.app/public/aB3xK9mP2q","ownerToken":"..."}. Save ownerToken.

Upload a file

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

Write a KV entry

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

Store a JSON document

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

Update in place (PUT)

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

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

Immutable on update: tags, password, format, filename, showTopBar. To change those, delete and recreate. Token workflow: /help#owner-token.

Resources & limits

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

TTL: default 15 days, max 30 days for every resource. After TTL the nightly cleanup job permanently deletes content — no recovery.

Integrate your AI agent

Three ways, easiest first:

SK Claude Code skill — brewdoc:publish docs →

Install the BrewPage publish skill in Claude Code:
  /plugin marketplace add kochetkov-ma/claude-brewcode
  /plugin install brewdoc@claude-brewcode
Then run /publish to share the current document.

MCP MCP server — brewpage-mcp docs →

Install the BrewPage MCP server for my agent:
  npx -y brewpage-mcp
Then register it under "brewpage" in my MCP config and restart.

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

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

Drop this into your agent’s system prompt

When you produce an HTML page, Markdown report, or any file the user should see — publish it to BrewPage and return the short URL. POST https://brewpage.app/api/html Content-Type: application/json Body: {"content":"<your HTML>"}. The response contains a short URL like brewpage.app/public/aB3xK9mP2q — give it to the user. Full reference: https://brewpage.app/llms.txt

Works with Claude Code Codex Gemini Cursor and more

LLM integration

Two text files describe the API for LLMs:

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

Ready-made prompts for Claude / ChatGPT / Cursor

Paste into the system prompt

Use https://brewpage.app/llms.txt as your quick reference for the BrewPage REST API.
When asked to publish a page, file, or JSON document, call the endpoints listed there.

Full-context variant

For the complete endpoint / field / error reference, fetch
https://brewpage.app/llms-full.txt and treat it as the authoritative BrewPage
API spec for this session.

Stats & views

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

What counts as a view?

The canonical definition of a view (which HTTP paths increment counters, today vs total, excluded paths) is the KDoc on backend/.../stats/StatsService.kt. When in doubt, that file is the source of truth.

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

BrewPage API — REST Reference