Developer quickstart
Zero to serving a verified open model into your app in minutes: get a self-serve API key, make your first call, resolve and pull a hosted model with SHA-256 verification, and connect an agent over MCP.
Serve verified open models into your own app in minutes. Public discovery needs no key; you only authenticate for account workflows. Every error is one typed envelope with a machine-readable next step, so there are no dead-ends.
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. Rate-limited per client; the same envelope carries Retry-After if you hit it.
curl -fsS -X POST 'https://huggingbay.xyz/api/account/reader-token' \
-H 'Content-Type: application/json' \
-d '{"displayName":"my app","purpose":"serving models"}'
# -> { "apiKey": { "token": "hbk_..." }, ... } (shown once)
export HUGGING_BAY_TOKEN="hbk_..."
2. Make your first call (no key required)
Search returns catalog rows with artifact ids. Every response carries requestId and cursor pagination; every error is one typed envelope { error, code, status, message, requestId, next: { action, href } }.
curl -fsS 'https://huggingbay.xyz/api/v1/search?q=embedding&limit=3&sort=best'
3. Serve 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 verify its SHA-256 locally. Pure curl works today with no install; the Python SDK does the resolve -> plan -> signed-URL download -> hash-verify -> attest chain for you.
# a) resolve to a catalog id
curl -fsS 'https://huggingbay.xyz/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2'
# b) read the hosted plan (files, sizes, sha256)
curl -fsS 'https://huggingbay.xyz/api/v1/artifacts/hf-model-sentence-transformers-all-minilm-l6-v2/download-plan'
# c) download a listed file and verify 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 verifies + attests for you.
# Install from a Hugging Bay checkout (PyPI is owner-gated): see https://huggingbay.xyz/python-sdk
python - <<'PY'
from hugging_bay import Client
c = Client()
plan = c.download_plan("hf-model-sentence-transformers-all-minilm-l6-v2")
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 verify-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 verify + 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 verify 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 serve URL — exists only for reviewed, hosted, license-clear artifacts; when nothing is hosted or the license forbids a mirror the plan is honestly empty (available:false), never a fabricated link. The SDK re-computes each file's SHA-256 against the plan before the file is published locally.
Open interactive page