vocabulary: '1.0.0'
info:
  provider: BrewPage
  description: >-
    Vocabulary for the BrewPage instant hosting platform. Captures the
    operational dimension (REST endpoints for hosted artifacts and storage)
    and the capability dimension (publish, share, store, retrieve, and
    govern transient web content with short URLs).
  created: '2026-05-16'
  modified: '2026-05-16'

operational:
  apis:
    - name: BrewPage API
      namespace: brewpage
      version: '1.51'
      baseUrl: https://brewpage.app
      status: active
  resources:
    - name: HTMLPage
      api: brewpage
      actions: [create, get, update, delete, getSource]
    - name: MarkdownPage
      api: brewpage
      actions: [create, get, update, delete]
    - name: File
      api: brewpage
      actions: [upload, download, delete, list]
    - name: Site
      api: brewpage
      actions: [upload, info, serveFile, delete]
    - name: KVStore
      api: brewpage
      actions: [create, list, listKeys, get, upsert, delete, deleteBucket]
    - name: JSONDocument
      api: brewpage
      actions: [create, get, update, delete, list]
    - name: ShortLink
      api: brewpage
      actions: [resolve, resolveWithSub]
    - name: Namespace
      api: brewpage
      actions: [random]
    - name: Preview
      api: brewpage
      actions: [previewImage, previewHtml]
    - name: Gallery
      api: brewpage
      actions: [browse]
    - name: AbuseReport
      api: brewpage
      actions: [submit]
    - name: Stats
      api: brewpage
      actions: [get]
    - name: OwnerCheck
      api: brewpage
      actions: [check]
    - name: Sitemap
      api: brewpage
      actions: [get]
  actions:
    - name: create
      method: POST
      pattern: write
    - name: upload
      method: POST
      pattern: write
    - name: get
      method: GET
      pattern: read
    - name: list
      method: GET
      pattern: read
    - name: update
      method: PUT
      pattern: write
    - name: upsert
      method: PUT
      pattern: write
    - name: delete
      method: DELETE
      pattern: destructive
    - name: deleteBucket
      method: DELETE
      pattern: destructive
    - name: resolve
      method: GET
      pattern: read
    - name: download
      method: GET
      pattern: read
    - name: browse
      method: GET
      pattern: read
    - name: check
      method: GET
      pattern: query
  enums:
    contentFormat:
      - html
      - markdown
      - md
    visibility:
      - public
      - namespaced
      - password-protected
    siteEntry:
      - index.html
      - index.htm
    ttlBounds:
      min: 1
      default: 15
      max: 30

capability:
  goals:
    - name: Publish Instant Web Page
      verbs: [create, upload]
      resources: [HTMLPage, MarkdownPage, Site]
    - name: Share Short Link
      verbs: [resolve]
      resources: [ShortLink, HTMLPage, File, Site]
    - name: Store AI Artifact
      verbs: [upload, create]
      resources: [File, JSONDocument, HTMLPage]
    - name: Iterate In Place
      verbs: [update, upsert]
      resources: [HTMLPage, JSONDocument, KVStore]
    - name: Govern Abuse
      verbs: [submit]
      resources: [AbuseReport]
    - name: Discover Public Content
      verbs: [browse]
      resources: [Gallery]
  primitives:
    - name: namespace
      description: Logical bucket for content. Default `public` lists on gallery; custom namespaces are private.
    - name: shortId
      description: 10-char server-issued identifier used in short URLs.
    - name: ownerToken
      description: Bearer-style token returned at creation; required (X-Owner-Token) for mutations and ownership grouping.
    - name: ttl
      description: Time-to-live in days, 1..30, default 15.
    - name: password
      description: Optional X-Password header (min 4 chars) that gates reads and removes content from gallery/sitemap.
    - name: userAgent
      description: Required User-Agent header on every request in the form AgentName/version.
  semanticTags:
    - Hosting
    - HTML
    - Markdown
    - AI Artifacts
    - File Hosting
    - Developer Tools
    - Short Links
    - Ephemeral Storage