{
"markdown": "# BrewPage API -- Open Source Public Layer\n\n[](https://www.npmjs.com/package/brewpage-mcp)\n[](https://github.com/kochetkov-ma/brewpage-openapi/stargazers)\n[](openapi/openapi.yaml)\n[](LICENSE)\n[](mcp-server/)\n\n> This repository is the **open-source public layer** of [BrewPage](https://brewpage.app) --\n> a proprietary HTML/KV/JSON/file hosting platform.\n> The backend, frontend, and infrastructure remain closed-source.\n\n**Docs:** https://kochetkov-ma.github.io/brewpage-openapi/ | **API Reference:** https://kochetkov-ma.github.io/brewpage-openapi/api-reference/\n\n## What is BrewPage\n\n[BrewPage](https://brewpage.app) is a free instant hosting service for HTML pages, Markdown documents,\nmulti-file sites, AI artifacts, JSON documents, key-value stores, and binary files.\nNo signup or API key required. Every published resource gets a short HTTPS URL\n(`brewpage.app/{namespace}/{id}`) within seconds.\n\nKey characteristics:\n\n- **HTML and Markdown pages** -- publish raw HTML or Markdown rendered to styled HTML, up to 5 MB, with instant short URLs.\n- **Multi-file sites** -- upload a ZIP archive or individual files (up to 20 MB / 100 files) and get a fully served static site.\n- **Key-value store** -- namespace-scoped KV pairs, up to 1,000 keys per namespace, mutable in place via the owner token.\n- **JSON documents** -- store and retrieve arbitrary JSON, up to 1 MB per document, 10,000 documents per collection.\n- **File hosting** -- upload any safe file type (images, PDFs, video, audio, archives, code), up to 5 MB (video 20 MB), with inline preview.\n- **Public namespace** -- omitting `?ns=` publishes to the shared `public` namespace, which is listed on the homepage gallery and indexed by search engines. Pass a custom namespace or `X-Password` header to keep content private.\n- **Owner tokens** -- every publish response includes an `ownerToken`. Use it to update content in place (stable URL), delete it, or list your own resources. No accounts, no sessions.\n- **TTL** -- content expires automatically. Default 15 days, maximum 30 days, configurable per request via `ttl_days`.\n- **No auth required** for reads. Writes are open (rate-limited to 60 uploads/hr per IP). All requests require a `User-Agent` header.\n\nBoth `brewpage.app` and `brewdata.app` serve the same API.\n\n## Why this matters for LLMs and agents\n\nAI agents frequently need to share structured outputs -- reports, artifacts, generated HTML, intermediate JSON state -- with users or downstream systems via a stable URL. BrewPage provides that as a zero-setup REST API: one `POST` call, one URL back. No OAuth, no S3 bucket configuration, no infrastructure. The MCP server (`brewpage-mcp`) wraps the API into six typed tools that any MCP-compatible agent (Claude, Codex, Gemini, Cursor) can call directly.\n\n## Quick Start\n\nPublish an HTML page and get a shareable link:\n\n```bash\ncurl -X POST https://brewpage.app/api/html \\\n -H \"Content-Type: application/json\" \\\n -H \"User-Agent: MyAgent/1.0\" \\\n -d '{\"content\": \"Hello, world!
\", \"ttlDays\": 15}'\n```\n\nResponse:\n\n```json\n{\n \"id\": \"aBcDeFgHiJ\",\n \"namespace\": \"public\",\n \"link\": \"https://brewpage.app/public/aBcDeFgHiJ\",\n \"ownerLink\": \"https://brewpage.app/api/html/public/aBcDeFgHiJ\",\n \"ownerToken\": \"your-secret-token\",\n \"expiresAt\": \"2026-06-04T02:00:00Z\",\n \"sizeBytes\": 22\n}\n```\n\nOpen `link` in any browser -- no further steps required.\n\n## Use Cases for LLMs and Agents\n\n| Scenario | API call |\n|----------|----------|\n| An AI agent generates a shareable HTML report and needs a stable URL to return to the user | `POST /api/html` -- returns link immediately |\n| A GPT pipeline needs to persist JSON state between conversation turns without external storage | `POST /api/json?ns=myproject` then `GET /api/json/myproject/{id}` |\n| A code-generation tool produces a downloadable file (PDF, archive, script) and needs to host it | `POST /api/files` -- file served with correct MIME type and inline preview |\n| An agent publishes an artifact and later refines it without invalidating the shared URL | `PUT /api/html/{ns}/{id}` with `X-Owner-Token` -- content replaced, URL unchanged |\n| A multi-step pipeline deploys a complete static site (HTML + CSS + JS) from a ZIP | `POST /api/sites` with `archive=@site.zip` -- all files served with relative links intact |\n\n## API Features\n\n| Resource | Description | Limits |\n|----------|-------------|--------|\n| **HTML pages** | Raw HTML or Markdown with instant short URLs | 5 MB, TTL 1--30d |\n| **Key-value store** | Named key-value pairs grouped in namespaces | 1,000 keys/namespace |\n| **JSON documents** | Store and retrieve arbitrary JSON with collection management | 1 MB, 10,000 docs/collection |\n| **Files** | Upload files with automatic MIME detection and inline preview | 5 MB (video 20 MB), 1,000 files/namespace |\n| **Sites** | Multi-file HTML sites via ZIP or individual files | 20 MB total, 100 files, 5 MB/file, TTL 1--30d |\n\nEvery resource gets a short URL (`brewpage.app/{ns}/{id}`), optional password protection, configurable TTL, and tagging. Public content appears in a browsable gallery with full-text search.\n\n## API Examples\n\n**Publish Markdown:**\n\n```bash\ncurl -X POST \"https://brewpage.app/api/html?format=markdown\" \\\n -H \"Content-Type: application/json\" \\\n -H \"User-Agent: MyAgent/1.0\" \\\n -d '{\"content\": \"# My Document\\n\\nHello **world**\"}'\n```\n\n**Store a JSON document:**\n\n```bash\ncurl -X POST https://brewpage.app/api/json \\\n -H \"Content-Type: application/json\" \\\n -H \"User-Agent: MyAgent/1.0\" \\\n -d '{\"name\": \"config\", \"version\": 1}'\n```\n\n**Upload a site (ZIP archive):**\n\n```bash\ncurl -X POST \"https://brewpage.app/api/sites\" \\\n -H \"User-Agent: MyAgent/1.0\" \\\n -F \"archive=@site.zip;type=application/zip\"\n```\n\n**Update content in place (stable URL):**\n\n```bash\ncurl -X PUT \"https://brewpage.app/api/html/public/aBcDeFgHiJ\" \\\n -H \"Content-Type: application/json\" \\\n -H \"User-Agent: MyAgent/1.0\" \\\n -H \"X-Owner-Token: your-secret-token\" \\\n -d '{\"content\": \"Updated content
\"}'\n```\n\n**Get platform stats:**\n\n```bash\ncurl https://brewpage.app/api/stats\n```\n\n## API Reference\n\n- **Interactive docs** -- [kochetkov-ma.github.io/brewpage-openapi](https://kochetkov-ma.github.io/brewpage-openapi/)\n- **API Reference (Scalar)** -- [kochetkov-ma.github.io/brewpage-openapi/api-reference](https://kochetkov-ma.github.io/brewpage-openapi/api-reference/)\n- **OpenAPI spec (YAML)** -- [`openapi/openapi.yaml`](openapi/openapi.yaml)\n- **OpenAPI spec (JSON)** -- [`openapi/openapi.json`](openapi/openapi.json)\n\n### Endpoints\n\n| Tag | Description |\n|-----|-------------|\n| **HTML** | Publish, retrieve, update, delete HTML/Markdown pages |\n| **KV** | Key-value store CRUD (get, set, list, delete keys) |\n| **JSON** | JSON document CRUD with collection listing |\n| **Files** | File upload, download, list, delete |\n| **Sites** | Multi-file site upload (ZIP or files), info, serve, delete |\n| **Gallery** | Browse public content with search and pagination |\n| **Stats** | Platform-wide usage statistics |\n| **Short Links** | URL shortener for published content |\n| **SEO** | Sitemap and robots.txt endpoints |\n| **Reports** | Abuse reports for published content |\n| **Namespace** | Collision-free namespace suggestions |\n\n## MCP Server\n\nThe `brewpage-mcp` package provides a Model Context Protocol server with **6 tools** for AI-assisted content publishing. See [`mcp-server/README.md`](mcp-server/README.md) for full documentation.\n\n| Tool | Description |\n|------|-------------|\n| `publish_html` | Publish HTML or Markdown content with optional password, TTL, filename, and top toolbar |\n| `publish_file` | Upload a file from a URL |\n| `publish_site` | Publish a single-page or multi-file HTML site |\n| `delete_resource` | Delete any resource (HTML, KV, JSON, file) by owner token |\n| `get_page` | Fetch a published HTML page and its content |\n| `get_stats` | Get platform-wide usage statistics |\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"brewpage\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"brewpage-mcp\"]\n }\n }\n}\n```\n\n### Claude Code\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"brewpage\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"brewpage-mcp\"]\n }\n }\n}\n```\n\n## Resources\n\n| Resource | URL |\n|----------|-----|\n| Live platform | https://brewpage.app |\n| LLM context file | https://brewpage.app/llms.txt |\n| Full LLM reference | https://brewpage.app/llms-full.txt |\n| OpenAPI spec (YAML) | [`openapi/openapi.yaml`](openapi/openapi.yaml) |\n| MCP server | [`mcp-server/`](mcp-server/) |\n| npm package | https://www.npmjs.com/package/brewpage-mcp |\n| Interactive API docs | https://kochetkov-ma.github.io/brewpage-openapi/ |\n| Claude skill | https://github.com/kochetkov-ma/claude-brewcode/tree/main/skills/brewpage-publish |\n| BrewCode plugin suite | https://github.com/kochetkov-ma/claude-brewcode |\n| Wiki | https://github.com/kochetkov-ma/brewpage-openapi/wiki |\n| Releases | https://github.com/kochetkov-ma/brewpage-openapi/releases |\n\nBrewPage is described using [schema.org/SoftwareApplication](https://schema.org/SoftwareApplication) structured data on the platform homepage.\n\n## What's Open Here\n\n| Component | Description |\n|-----------|-------------|\n| OpenAPI 3.1 spec | Complete API contract for all public endpoints (YAML + JSON) |\n| Interactive docs | Astro + Scalar documentation site (GitHub Pages) |\n| MCP server | `brewpage-mcp` -- Claude Desktop/Code integration (6 tools) |\n| Wiki | Code snippets, cheatsheet, tips & tricks |\n| Release notes | Changelog for API and public tooling |\n\n## What's Proprietary\n\n| Component | Description |\n|-----------|-------------|\n| Backend | Spring Boot + Kotlin REST API |\n| Frontend | HTML/CSS/JS + Caddy reverse proxy |\n| Infrastructure | VPS deployment, CI/CD pipelines |\n| E2E test suite | Playwright + Testcontainers |\n\n## Project Structure\n\n```\nbrewpage-openapi/\n openapi/\n openapi.json # OpenAPI 3.1 spec (JSON)\n openapi.yaml # OpenAPI 3.1 spec (YAML)\n docs-site/ # Astro documentation site\n src/\n pages/ # Documentation pages\n components/ # Scalar API reference\n mcp-server/ # MCP server (brewpage-mcp)\n src/\n index.ts # Server entry point\n .github/\n workflows/ # CI/CD (docs deploy, releases)\n README.md\n RELEASE-NOTES.md\n LICENSE\n```\n\n## License\n\n[Apache 2.0](LICENSE)\n\n",
"bytes": 10870,
"sha": "adf2a3ce3c85cee9c3eeb170532c82476b928225444cac2fbe30532ba2ede71b",
"repo_slug": "kochetkov-ma/brewpage-openapi",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_kochetkov_ma_brewpage_mcp_a4835f72/readme"
}