BrewPage Preview API

openapi: 3.2.0
info:
  title: BrewPage Preview 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: Preview
  description: 'Social previews: per-content OpenGraph image (1200×630 JPEG; .png is a legacy URL alias) and OG meta stub for social bots'
paths:
  /preview/{ns}/{id}.png:
    get:
      tags:
      - Preview
      summary: Per-content OG image (legacy URL)
      description: 'Legacy alias of /preview/{ns}/{id}.jpg for links shared earlier: serves the same JPEG card with identical bytes, headers and fallbacks'
      operationId: preview
      parameters:
      - name: ns
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Image bytes
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '302':
          description: Fallback to static og-image.png (flag off, no source, render gate busy, error)
        '304':
          description: Not modified (If-None-Match matched current ETag)
        '429':
          description: Per-IP rate limit exceeded
  /preview/{ns}/{id}.jpg:
    get:
      tags:
      - Preview
      summary: Per-content OG image
      description: 'Canonical og:image URL. Returns the 1200×630 JPEG card, cached, with ETag/If-None-Match support; non-public namespaces and protected content add X-Robots-Tag: noindex; falls back to /og-image.png?v=3 on any failure'
      operationId: previewJpeg
      parameters:
      - name: ns
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Image bytes
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '302':
          description: Fallback to static og-image.png (flag off, no source, render gate busy, error)
        '304':
          description: Not modified (If-None-Match matched current ETag)
        '429':
          description: Per-IP rate limit exceeded
  /preview-html/{ns}/{id}:
    get:
      tags:
      - Preview
      summary: OpenGraph HTML stub
      description: Tiny HTML response with og:title/og:description/og:image meta tags for social-bot unfurls
      operationId: previewHtml
      parameters:
      - name: ns
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: HTML stub with OG meta (or generic stub when resource is missing)
          content:
            text/html:
              schema:
                type: string
components:
  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)