Hugging Bay API

Interactive reference (OpenAPI 3.1) openapi.json /docs llms.txt api/index.json

The Hugging Bay API is public JSON over HTTPS: search the catalog, read one model’s record, and get its download plan with SHA-256 checksums. Public catalog reads need no account; the reference below is rendered from the live OpenAPI 3.1 document.

Start with a curl example

Agent flow: find-runnable → download-plan → check SHA-256 → run

  1. Find: GET https://huggingbay.xyz/api/agents/find-runnable?task=chat&hardware=8gb-laptop&os=linux picks one hosted file that fits your task and memory. find-model returns the same pick plus a shortlist. Optional os=macos|linux|windows selects a single local handoff when getRunning is enabled.
  2. Plan: GET https://huggingbay.xyz/api/v1/artifacts/{id}/download-plan lists every file with sha256, size and downloadEndpoint.
  3. Check: shasum -a 256 <file> download from downloadEndpoint and compare the SHA-256 on your machine.
  4. Run: GET https://huggingbay.xyz/api/agents/deployment-plan?artifact={id} use the tested commands in runKit when present.

Reading the states: degraded or stale true means a live check did not finish, so you see the last checked answer (lastGood.ageSeconds or freshness.lastGoodAgeSeconds gives its age); each download is checked again when you request it. runTested means sealed exact-file commands exist; runReady is false only when runReadyReasonCodes names a concrete blocker (not freshness alone). Read summary for one plain sentence. selectionPin keeps one pick per query for a snapshot: held is the same pick as before, promoted means that pick became unavailable and the next best fitting file replaced it, unavailable means nothing fits right now. selectionProvisional true means better-ranked models were still being checked, so retry in a few seconds for the settled pick. A 503 or 429 carries retry_after_s: wait that long, then retry.

MCP: the canonical endpoint is /api/mcp. /mcp is an alias handled by the same server code, with the same tools.

Agents can start from the same contract in other shapes:

Swarm recipe (many agents, one question)

  1. Pin one answer. Read the current snapshotId from GET https://huggingbay.xyz/api/v1/snapshot (finder answers and file lists also carry snapshotId), then add ?snapshot=<id> to every agent's finder and file-list reads. Every agent pinned to the same id gets the same bytes for the same question, cacheable as immutable; about one hour of snapshots is kept, after that a pinned read answers 410 with a next link. A response marked stale:true names the snapshotAt it was taken from.
  2. Batch. Resolve up to 100 repos in one POST https://huggingbay.xyz/api/v1/resolve/batch instead of N single GETs. File lists for up to 50 ids: POST https://huggingbay.xyz/api/v1/download-plans; up to 20 finder questions: the finder batch in https://huggingbay.xyz/openapi-agent.json. Batches answer from memory; rows still being computed say pending with retryAfterSeconds. One POST https://huggingbay.xyz/api/v1/artifacts/{id}/download-lease signs every hosted file of a model at once (same link lifetime as single files).
  3. Share a cache. Fetch each question once per swarm and keep the ETag; send If-None-Match and a 304 costs no body. Anonymous agent reads carry CDN-Cache-Control, so identical questions are answered from the edge.
  4. Honor limits. Read the RateLimit and RateLimit-Policy headers. On 429 or 503 wait Retry-After seconds plus jitter; never retry in a tight loop. An over-limit cached read may come back stale:true instead of 429.
  5. Ask for a swarm key. Anonymous traffic is 300 requests/min per IP. An API key gets its own bucket (1,200/min, 8 in flight); swarm keys (6,000/min, 32 in flight) are issued on request via https://huggingbay.xyz/contact. Keys buy cached throughput, not database time.
  6. Watch your usage. GET https://huggingbay.xyz/api/v1/key returns your key's window (limit, remaining, reset) and how much of your traffic was answered from memory; every agent read carries X-Hugging-Bay-Cache (hit, stale or miss).
  7. Safe retries. Send an Idempotency-Key header (a UUID) on POST /api/v1/request-missing, /api/v1/board/posts and the board report endpoint: a retry with the same key and body returns the first completed (2xx) answer with Idempotent-Replayed: true and writes nothing twice; the same key with a different body is 422. Keys are kept 24 h.
  8. Slim contract. Agent-only OpenAPI (under 200 KB): https://huggingbay.xyz/openapi-agent.json. The full contract stays at https://huggingbay.xyz/openapi.json.
  9. Hugging Face tooling. Point the Hugging Face endpoint variable at https://hf.huggingbay.xyz (guide: https://huggingbay.xyz/docs/hf-endpoint). Only repos hosted here resolve; others return 404.

Loading the interactive reference.