# Hugging Bay

Hugging Bay is an open AI artifact discovery catalog with selective verified mirrors.
Use it as broad metadata discovery first. Treat hosted downloads as available only when hosting status and manifests say files are hosted by Hugging Bay.

## Safe Agent Workflow
- Start here: https://huggingbay.xyz/api/agents/briefing
- Search: https://huggingbay.xyz/api/artifacts?summary=1&q=<query>&limit=20
- Open-source radar: https://huggingbay.xyz/api/radar
- Inspect artifact: https://huggingbay.xyz/api/artifacts/{id}
- Inspect agent metadata: https://huggingbay.xyz/api/artifacts/{id}/metadata.json
- Single-call artifact bundle: https://huggingbay.xyz/api/artifacts/{id}/agent-bundle
- Artifact card: https://huggingbay.xyz/api/artifacts/{id}/card and https://huggingbay.xyz/api/artifacts/{id}/card.md
- Compare artifacts: https://huggingbay.xyz/api/compare?ids=<id1>,<id2>
- Inspect files: https://huggingbay.xyz/api/artifacts/{id}/files?limit=100
- Preview hosted text file: https://huggingbay.xyz/api/previews/{id}/{url_encoded_path}
- Hosted files only: https://huggingbay.xyz/api/downloadable-files?limit=100
- Mirror readiness: https://huggingbay.xyz/api/mirror-readiness?limit=50
- Large publisher upload sessions: https://huggingbay.xyz/api/upload-sessions
- Source policy: https://huggingbay.xyz/api/sources and https://huggingbay.xyz/.well-known/catalog-sources.json
- Source coverage: https://huggingbay.xyz/api/sources/github/coverage
- Agent task workflows: https://huggingbay.xyz/api/agents/tasks
- Publisher workflow: https://huggingbay.xyz/api/agents/publisher-workflow
- Stack packs: https://huggingbay.xyz/api/stacks
- Intent URL batches: https://huggingbay.xyz/api/indexing/urls?kind=intent&limit=100
- Agent manifest: https://huggingbay.xyz/.well-known/ai-catalog.json
- MCP manifest: https://huggingbay.xyz/.well-known/mcp.json
- API contract: https://huggingbay.xyz/openapi.json and https://huggingbay.xyz/api/schemas
- Indexing status: https://huggingbay.xyz/api/indexing/status
- Bounded URL batches: https://huggingbay.xyz/api/indexing/urls?kind=artifact&limit=1000&cursor=0
- Agent-doc URL batches: https://huggingbay.xyz/api/indexing/urls?kind=agent-doc&limit=100
- Source URL batches: https://huggingbay.xyz/api/indexing/urls?kind=source&limit=1000&cursor=0
- Server-rendered artifact, ranking, topic, source, stack, and download pages include schema.org JSON-LD for crawler and agent extraction.

## Authenticated Operator Endpoints
- These require a bearer token and should be used with bounded limits and explicit run ids.
- Import runs: https://huggingbay.xyz/api/admin/imports?limit=50 and https://huggingbay.xyz/api/admin/imports/{runId}
- Job state: https://huggingbay.xyz/api/admin/jobs
- Storage check: POST https://huggingbay.xyz/api/admin/storage/check
- HF metadata plan: POST https://huggingbay.xyz/api/admin/imports/huggingface/plan
- HF worker batch: POST https://huggingbay.xyz/api/admin/imports/huggingface/worker/run
- HF detail expansion: POST https://huggingbay.xyz/api/admin/imports/huggingface/detail-expand
- Source metadata plan: POST https://huggingbay.xyz/api/admin/imports/sources/plan
- Source worker batch: POST https://huggingbay.xyz/api/admin/imports/sources/worker/run
- Mirror queue: https://huggingbay.xyz/api/admin/mirror-queue?limit=50 and POST https://huggingbay.xyz/api/admin/mirror-queue/run
- Admin traffic summary: https://huggingbay.xyz/api/admin/traffic

## Rules For Agents
- Use summary=1 plus limit/cursor for catalog scans.
- Add facets=1 only when global facet counts are required; ordinary scans should use fast row pages.
- Use indexing URL batches for crawl/submission work; do not scrape unbounded UI pages.
- Use source coverage pages to understand provider scope and policy before importing or crawling source-specific records.
- Use mirror readiness for blockers, safe file candidates, and tool compatibility before mirror requests.
- Use agent task workflows for high-intent work before broad search fanout.
- Use the publisher workflow endpoint before applying for namespace access or uploading releases.
- Use artifact bundles to avoid multi-endpoint fanout when inspecting short-listed records.
- Use artifact cards and compare payloads to inspect short lists before download or mirror requests.
- Use file previews only for hosted text-like files; external metadata rows stay upstream.
- Use upload sessions for large releases; do not base64-encode large model shards into JSON.
- Do not assume external Hugging Face metadata rows are downloadable from Hugging Bay.
- Do not assume GitHub, arXiv, OpenML, Zenodo, OpenDataLab, OpenCompass, or other metadata rows are downloadable from Hugging Bay.
- Do not attempt gated/private/license bypasses.
- Prefer permissive-license, scan-passed, verified, hosted rows for automated download workflows.
- Request a mirror with POST /api/artifacts/{id}/mirror-request when a public external Hugging Face artifact should be reviewed for hosting.
- Admin endpoints require configured bearer tokens and are not public crawler surfaces.

## Publisher Workflow
- Human application page: https://huggingbay.xyz/publishers/apply
- Public application API: POST https://huggingbay.xyz/api/publisher-applications
- Agent workflow: https://huggingbay.xyz/api/agents/publisher-workflow
- CLI application: bay publisher-apply application.json --api https://huggingbay.xyz
- Applications are manual review requests, not automatic account creation.
- Approved publishers use bearer tokens, upload sessions, release checks, and publish endpoints.