canonical: https://jentic.com/apis/brewpage.app/brewpage

# Brewpage App BrewPage API

The BrewPage API publishes HTML pages, Markdown, JSON documents, key-value stores, single files, and multi-file sites to instant short links on brewpage.app. Each publication lives under a namespace and id, can carry a reader password, a ttl, and tags, and can be listed publicly with ns=public or kept unlisted in a private namespace. Owners holding an X-Owner-Token can update or delete what they published, rotate a link, reset its management key, read per-publication stats, and attach a custom hostname. Anonymous publishing works for the create and read routes, so a client can host content before it has any token.

## For AI agents

Publish HTML, Markdown, JSON, files, key-value stores, and zipped sites to shareable brewpage.app links, then update, password-protect, rotate, or delete them with an owner token.

## Scope

Does not handle build pipelines, serverless functions, databases with queries, or domain registration. Use for publishing pages, files, JSON, and key-value data to shareable links only.

## Capabilities

- Publish an HTML or Markdown page to a short link with POST `/api/html`, with optional ttl, tags, and reader password
- Host a JSON document and fetch or replace it later by namespace and id
- Create a key-value store and upsert, read, list, or delete individual keys
- Upload a single file or a multi-file site archive and serve its files from one link
- Rotate a publication's link, reset its management key, or set a reader password through X-Owner-Token or X-Manage-Key
- Attach a custom hostname to a publication and check its DNS status
- Read view stats for a publication and list everything published under your owner profile

## Use cases

### AI agent publishing its output as a shareable page

A coding or research agent that produces an HTML report needs somewhere to put it that a human can open. Through Jentic the agent searches for 'publish an HTML page', loads the BrewPage create_1 operation, and posts the page body to POST `/api/html` with a private namespace and an optional X-Password. BrewPage returns the link and a management URL, and the owner token is injected by Jentic on later updates so the agent can revise the same page instead of publishing duplicates.

Example prompt: POST a generated HTML report to `/api/html` with a ttl and an X-Password header, return the link to the user, then update it via PUT `/api/html/{ns}/{id}` after a correction

### Lightweight key-value state for scripts and agents

Scripts and agents that run in separate sessions often need a tiny shared store for a cursor, a flag, or a last-run timestamp. BrewPage creates a key-value bucket with POST `/api/kv`, then exposes per-key reads, upserts, and deletes under `/api/kv/{ns}/{id}/{key}.` A password on the bucket keeps casual readers out, and the whole bucket can be removed in one call when the job ends.

Example prompt: Create a KV store with POST `/api/kv` using key 'last_run' and a timestamp value, then upsert the key via PUT `/api/kv/{ns}/{id}/{key}` on each run and read it back with GET `/api/kv/{ns}/{id}/{key}`

### Static site and file drop

A developer who wants to show a prototype or hand over a build artifact can upload a site archive or a set of files to POST `/api/sites`, or a single file to POST `/api/files.` BrewPage serves the site's files from one short link, and the owner can republish with PUT `/api/sites/{ns}/{id}` or replace a file with PUT `/api/files/{ns}/{id}` without changing the URL.

Example prompt: Upload a zipped prototype via POST `/api/sites` with an archive part and entry index.html, then republish an updated archive with PUT `/api/sites/{ns}/{id}`

### Custom domain and link hygiene

Owners who outgrow the default link can add a hostname to their profile with POST `/api/domains`, attach a publication to it with PUT `/api/domains/{hostname}/attachment`, and trigger a DNS check with POST `/api/domains/{hostname}/check.` If a link has been shared too widely, POST `/api/{type}/{ns}/{id}/rotate` issues a new id and the old link stops working, and the management link can be reset the same way.

Example prompt: Add docs.example.dev with POST `/api/domains`, attach an HTML publication via PUT `/api/domains/{hostname}/attachment` with type, ns, and id, then run POST `/api/domains/{hostname}/check`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/html` | Create an HTML page |
| PUT | `/api/html/{ns}/{id}` | Update an HTML page |
| POST | `/api/json` | Create a JSON document |
| POST | `/api/kv` | Create a key-value store |
| PUT | `/api/kv/{ns}/{id}/{key}` | Upsert a key |
| POST | `/api/sites` | Upload a site |
| POST | `/api/files` | Upload a file |
| GET | `/api/publications` | List my publications |

## Key resources

- **HTML pages** — Create, read, update, and delete HTML or Markdown pages, plus raw source and settings for owners
- **JSON documents** — Host, list, replace, and delete JSON documents by namespace and id
- **Key-value stores** — Create buckets and read, upsert, list, or delete individual keys
- **Files and sites** — Upload single files or multi-file site archives and serve their contents
- **Publications** — Owner-level listing, stats, passwords, visibility, link rotation, and hosting settings
- **Domains and owner tokens** — Custom hostnames with DNS checks, and minting, binding, or revoking profile tokens

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 53 / 100
- **Maturity:** Non-Ready
- **Dimensions:**
  - Foundational Compliance: 35 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 45 / 100
  - Agent Usability: 90 / 100
  - Security: 50 / 100
  - AI Discoverability: 74 / 100
- **View full report:** https://jentic.com/apis/brewpage.app/brewpage/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring BrewPage by hand means juggling three header credentials: X-Owner-Token for your profile, X-Manage-Key per publication, and X-Password for protected reads, and remembering which routes accept anonymous calls. Through Jentic you install once, import BrewPage from the API Directory, store the owner token once, and your agent calls it.
- **Permission scoping:** BrewPage puts the namespace and publication id in the URL path (`/api/html/{ns}/{id}`, `/api/kv/{ns}/{id}/{key}`), so a rule can pin your agent to one namespace or one publication for updates, reads, and deletes. Creates carry ns as a query parameter, so for those a rule bounds which operations the agent may call. You choose the operations it may call, so destructive ones like DELETE `/api/kv/{ns}/{id}` or POST `/api/owner-token/revoke-others` are not included unless you add them.
- **Credential handling:** Your BrewPage owner token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'publish an HTML page' or 'store a key value', and Jentic returns the matching BrewPage operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Netlify API** — Full site deployment platform with builds, functions, and DNS, heavier than BrewPage's instant links.
- **Pastebin API** — Text paste hosting for snippets and logs rather than rendered HTML or sites.
- **GitHub v3 REST API** — Source control and Gists, often the origin of the content an agent then publishes.

## FAQ

### What authentication does the BrewPage API use?

The BrewPage OpenAPI spec declares three header schemes: OwnerToken (the X-Owner-Token header) identifies your owner profile, ManageKey (the X-Manage-Key header, taken from a publication's manageUrl) gives full control of one publication, and Password (the X-Password header) unlocks a password-protected publication for reading. Many create and read routes, such as POST `/api/html` and GET `/api/json/{ns}/{id}`, accept anonymous calls, while profile routes like GET `/api/publications` and the `/api/domains` family need X-Owner-Token. A fresh owner token can be minted with GET `/api/owner-token.`

### Can I store small pieces of state with the BrewPage API?

Yes. POST `/api/kv` creates a key-value store with an initial key and value, PUT `/api/kv/{ns}/{id}/{key}` upserts a key, GET `/api/kv/{ns}/{id}/{key}` reads it, and GET `/api/kv/{ns}/{id}` lists the keys. DELETE `/api/kv/{ns}/{id}` removes the entire bucket. Adding an X-Password at creation keeps readers without the password out.

### What are the rate limits for the BrewPage API?

The OpenAPI spec does not specify request rate limits. GET `/api/limits` returns the upload size limits per publication type, which is the figure to check before posting a large file or site. For current usage terms, see https://brewpage.app/terms.

### Is there a BrewPage MCP server?

You don't need an MCP server to give your agent BrewPage. Jentic connects it directly from the API Directory: import it, store your owner token once, and your agent calls the publish and update operations it needs, discovered on demand rather than loaded as tool definitions into its context.

### Can I limit what my agent is allowed to do with BrewPage?

Yes. For example, write a rule that allows only POST `/api/html` and PUT `/api/html/{ns}/{id}` under your own namespace, so the agent can publish and revise pages but cannot call DELETE routes, rotate links, mint owner tokens, or change domains. Every call it makes is recorded in the audit log.

### How do I publish a page through Jentic?

Add BrewPage to your Jentic One instance from the directory and store your X-Owner-Token. Your agent then searches for 'publish an HTML page', loads the create_1 operation for POST `/api/html`, and sends the page body with an optional ttl and tags. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is a private BrewPage link the same as a protected one?

No. The spec notes that a private link is not a lock: anyone holding it can open the publication. To restrict reading, set a password with POST `/api/{type}/{ns}/{id}/password` or send X-Password on create, and use POST `/api/{type}/{ns}/{id}/access/revoke` to revoke reader access to a protected publication.
