Find a model. Check the file yourself.
Search the catalog with no key. Download hosted files. Each file carries a SHA-256 fingerprint — compare it on your machine. Save finds with a self-serve reader token.
General API errors carry a code, plain message, and support id. Notification routes have their own error shapes; paused subscriptions have no retry step.
Audit 2026-10-01: MCP answers discovery; public reads are available; urllib at the public edge is unverified. Other surface observations are dated in /api/agent-discovery → status.
1. Get an API key (self-serve, no signup)
Public reads need no token, so you can skip this for search/resolve/download-plan. For account workflows POST /api/account/reader-token with no prior authentication — the token is shown once, save it. Not sure which key you need? Read the three doors at /quickstart/keys.
curl -fsS -X POST 'https://huggingbay.xyz/api/account/reader-token' \
-H 'Content-Type: application/json' \
-d '{"displayName":"my app","purpose":"saving finds"}'
# -> { "apiKey": { "token": "hbk_..." }, ... } (shown once)
export HUGGING_BAY_TOKEN="hbk_..."
Run models (Bay Run)
A separate service for running small specialist models — different origin, different key. Public reads on this site need no key; account workflows use the reader token above; running models uses a free Bay Run key.
# START HERE → mint a free key (last checked 2026-09-26)
BAY_RUN_KEY=$(curl -sS -X POST 'https://run.huggingbay.xyz/v1/keys/free' -H 'content-type: application/json' -d '{}' | python3 -c "import json,sys; print(json.load(sys.stdin)['key'])")
# First run — uses the key from the line above, nothing to paste
curl -sS -X POST 'https://run.huggingbay.xyz/v1/run/route_00857aa05f863c2cdba0e908366b2cca' -H "Authorization: Bearer $BAY_RUN_KEY" -H 'content-type: application/json' -d '{"input":"The quick brown fox jumps over the lazy dog."}'
Which key do I need? Reader token = your account on this site (notify, watchlists). Free Bay Run key = running models on run.huggingbay.xyz. OAuth demo grant exists for agents that prefer it — Bay Run skill has the full contract.
Free keys are for trying things: 500 tasks a day per key. Errors are JSON and tell you the next step — a bad token hands you the mint command, a wrong path points at the OpenAPI document.
2. Make your first call (no key required)
Search returns catalog rows with artifact ids. For task-first discovery use find-model (the live /api/agents/find-model route) with a task and an optional hardware preset. Cursor pagination applies to list endpoints that document cursor and nextCursor; health and download plans are not paginated. General API errors carry a support id (request_id and requestId) and a next step. Notification subscribe and lookup errors use request_id; confirmation and unsubscribe errors have separate shapes. Paused subscribe and lookup responses return next: null and retryable: false.
# a) catalog search
curl -fsS 'https://huggingbay.xyz/api/v1/search?q=embedding&limit=3&sort=best'
# b) task-first discovery — find_model, matching the live API
curl -fsS 'https://huggingbay.xyz/api/agents/find-model?task=embeddings&hardware=8gb-laptop&limit=3'
3. Download a hosted model into your app
Resolve an upstream repo (or use an id from search) -> read the hosted download plan (per-file sha256 + size; honestly empty when nothing is hosted or the license does not permit a mirror) -> download a file from the plan's downloadUrl and check its SHA-256 locally. Pure curl works today with no install; the Python SDK does the resolve -> plan -> signed-URL download -> hash check -> attest chain for you.
# a) resolve to a catalog id (artifactId is the one id key every surface uses)
ID=$(curl -fsS 'https://huggingbay.xyz/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2' | jq -r .artifactId)
# b) read the hosted plan (files, sizes, sha256) for that exact id
curl -fsS "https://huggingbay.xyz/api/v1/artifacts/$ID/download-plan"
# c) download a listed file and check its sha256 locally (no install)
curl -fL '<downloadUrl from the plan>' -o model.bin
printf '%s model.bin\n' '<sha256 from the plan>' | shasum -a 256 -c -
# Ergonomic path — the Python SDK checks + attests for you.
# Official install (no PyPI): https://huggingbay.xyz/python-sdk (do NOT 'pip install hugging-bay' — see https://huggingbay.xyz/install)
python - <<'PY'
from hugging_bay import Client
c = Client()
# task-first discovery — find_model matches the live /api/agents/find-model route
pick = c.find_model("embeddings", device_family="laptop", limit=3)
plan = c.download_plan("hf-model-sentence-transformers-all-minilm-l6-v2")
lock = c.lock("hf-model-sentence-transformers-all-minilm-l6-v2") # signed manifest that pins the exact bytes
for f in plan["files"]:
c.download_file("hf-model-sentence-transformers-all-minilm-l6-v2", f["path"], f["path"],
sha256=f["sha256"], size_bytes=f["sizeBytes"])
PY
4. Connect an agent (MCP) or install the tools
The same catalog is a first-class MCP server (remote + stdio, self-describing). Point any MCP client at the remote endpoint, or use the documented install channels.
# Remote MCP (list the self-describing tools)
curl -fsS 'https://huggingbay.xyz/api/mcp' -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Manifest + one-file server card
curl -fsS 'https://huggingbay.xyz/.well-known/mcp.json'
# Connection guide + install channels (CLI, stdio MCP, SDK):
# https://huggingbay.xyz/developers/mcp https://huggingbay.xyz/install https://huggingbay.xyz/python-sdk
JavaScript / TypeScript
The read path is a plain fetch; the check-and-attest download path lives in the Python SDK and CLI.
// Node 18+ / browsers: reads need no key. Send Authorization: Bearer <token>
// only for account workflows. Downloads use short-lived signed URLs — use the
// Python SDK (or the CLI) for the check + attest step.
const BASE = "https://huggingbay.xyz";
// 1. search
const rows = await fetch(`${BASE}/api/v1/search?q=embedding&limit=3`).then(r => r.json());
// 2. resolve -> id, then read the hosted plan
const resolved = await fetch(`${BASE}/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2`).then(r => r.json());
const plan = await fetch(`${BASE}/api/v1/artifacts/${resolved.artifactId}/download-plan`).then(r => r.json());
// plan.files[].sha256 / .sizeBytes are what you check after download.
Reference and honesty rules
Copy-paste API recipes live under /api and the full interactive contract at /docs/api (OpenAPI 3.1). A download plan — and therefore a download URL — exists only for reviewed, hosted artifacts; when nothing is hosted the plan is honestly empty (files: [] and serve.downloadReady: false), never a fabricated link. The SDK re-computes each file's SHA-256 against the plan before the file is published locally.
Intents are capped at 2000 characters; input is never echoed back raw. A request the abuse filter blocks answers 403 request_blocked as JSON — nothing was processed and nothing was used up.
Which key do you need? (three doors)
Open interactive page