huggingbay-xyz Catalog API

openapi: 3.2.0
info:
  title: Hugging Bay Public Catalog API
  version: 0.2.0
  summary: AI artifact discovery, provenance, hosted/external state, and mirror demand APIs.
  x-agent-quickstart: '## Connect your agent

    One live call; public reads need no key:


    ```sh

    curl -fsS ''https://huggingbay.xyz/api/mcp'' -H ''Content-Type: application/json'' -d ''{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_artifacts","arguments":{"q":"Qwen2.5 0.5B GGUF","limit":5}}}''

    ```


    Hosted MCP: Streamable HTTP `https://huggingbay.xyz/api/mcp`. No key for reads. Inspect tools/list.

    Claude Code: `claude mcp add --transport http hugging-bay https://huggingbay.xyz/api/mcp`

    Codex CLI: `codex mcp add hugging-bay --url https://huggingbay.xyz/api/mcp`. Public reads need no OAuth login.

    Cursor: add {"mcpServers":{"hugging-bay":{"url":"https://huggingbay.xyz/api/mcp"}}} to .cursor/mcp.json.

    ChatGPT: On ChatGPT web, open Plugins → + → Add custom MCP server. Name it hugging-bay, paste this remote MCP URL, choose no authentication, and review the search and fetch tools for public catalog reads. Availability depends on your account and workspace permissions. This custom connection is separate from the private bundled plugin; public-directory approval remains separate. URL: https://huggingbay.xyz/chatgpt/mcp

    Stdio (Node.js 18+): `npx -y hugging-bay-mcp@0.1.13`; list tools.

    On 2026-10-29 the official MCP Registry listed io.github.barneywohl/hugging-bay 0.1.13 as active and latest.

    The call returns a live catalog row. Read its file and license details before downloading.

    Fit is an estimate. A hash checks bytes; it does not prove a run, safety or license permission.'
  description: 'Agents can request models, features, tools and builds, get an id, check the status of each request, and read a public changelog of what shipped. Missing a model, file, tool or feature? Ask with request_feature (MCP) or POST https://huggingbay.xyz/api/v1/requests. No account. You get an id and can check its status. What shipped: https://huggingbay.xyz/changelog Start at /api/index.json for bounded open-model and dataset discovery, license and provenance metadata, hosted-file evidence, MCP profiles and explicit execution boundaries. Catalog inclusion is not proof of byte availability, runtime readiness or quality. Authenticated operations require the documented scopes; discovery never grants authority to execute them.


    **Data freshness.** `degraded` means a fresh complete read was unavailable; `stale` means earlier snapshot data is being shown. Neither flag grants download or execution permission. See `x-data-freshness`.


    **Private notifications.** The site''s `/v1/notify/*` browser/email routes are listed under `x-private-routes`, including their paused and one-click behavior.'
  x-changelog:
  - version: 0.2.0
    date: '2026-10-16'
    changes:
    - 'Identified the Round 9 path addition: POST /api/events/a2hs (createA2hsEvent), the aggregate home-screen tip counter added on 2026-10-15. Its schema requires event, surface and platform plus the same-origin CSRF header; it stores no visitor identifiers.'
    - Clarified IP and route-group read budgets, uncached RateLimit headers, and the separate live database concurrency admission limits under x-rate-limit.admission. Capacity 503s do not imply a fixed requests-per-second throttle.
    - /api/programs is not served on huggingbay.xyz or run.huggingbay.xyz. Read hosted Bay Run Pins at https://run.huggingbay.xyz/v1/pins; the separate browser model manifest is https://huggingbay.xyz/run/api/programs.
  - version: 0.2.0
    date: '2026-10-12'
    changes:
    - Hosted-file JSONL routes and their latest-data alias return JSON errors instead of zero-byte successful downloads when no rows are available; nonempty dumps retain their row format and continuation links.
    - Unknown agent-request ids return request_not_found, including malformed ids. /changelog/ redirects to /changelog, which shares agent-request shipping entries with /api/v1/changelog; /what-changed remains the separate serve-decision feed.
    - OpenAPI contract version follows this changelog instead of the MCP package version. Data freshness flags and private browser notification routes are documented separately from public SDK operations.
  - version: 0.2.0
    date: '2026-09-21'
    changes:
    - 'Consolidated developer reference: the authentication policy, the rate-limit policy (x-rate-limit), the error taxonomy (x-error-taxonomy), this changelog (x-changelog) and a loud deprecated-alias map (x-deprecated-aliases) are now carried in this one document, so openapi.json is the single source instead of the scattered install/PyPI/blackboard/SKILL surfaces.'
    - Published a pointer to the observed remote MCP tools/list contract (x-mcp) so an agent can discover the model-discovery and download tools, not only the fixed Bay Run demo Pins.
  - version: 0.2.0
    date: '2026-09-20'
    changes:
    - 'General API error envelope: { error, code, status, message, requestId, next:{action,href} }; notification routes have separate documented shapes. nextAction and docsRef remain as deprecated aliases.'
    - recorded-vs-alias markers (x-primary, x-primary-path, x-aliases) and near-synonym disambiguation (x-route-family, x-use-when) on every duplicated route.
    - 'Runnable examples: request parameter examples, a JSON response example and an x-codeSamples curl recipe on the core operations.'
    - 'Edge validation: malformed numeric query parameters are rejected with 400 invalid_query before reaching the database.'
  - version: 0.2.0
    date: '2026-09-19'
    changes:
    - 'Developer on-ramp: /quickstart (get a key, first call, serve a model), the rendered reference at /docs/api (Redoc over this spec), self-serve reader tokens, and an llms.txt mirror of the same steps.'
servers:
- url: https://huggingbay.xyz
tags:


# --- truncated at 32 KB (320 KB total) ---
# Full source: https://artifacts.apis.io/huggingbay-xyz/openapi/huggingbay-xyz-catalog-api-openapi.yml