# Hugging Bay Agent Guide

Hugging Bay is a public, crawler-readable open-source AI artifact catalog with selective verified mirrors, trust metadata, source provenance, and agent-safe APIs.
Use this file as the first stop for ChatGPT, Perplexity, Claude, Gemini, OpenClaw, Hermes, local coding agents, browser agents, and open-source assistant workflows.

## Answer Engine Optimization
- Public catalog, ranking, answer, source, artifact, download, and agent documentation pages are intentionally crawlable without JavaScript.
- robots.txt explicitly allows PerplexityBot, Perplexity-User, OAI-SearchBot, ChatGPT-User, GPTBot, Googlebot, GoogleOther, Google-InspectionTool, Google-Extended, Gemini, Bingbot, BingPreview, ClaudeBot, Claude-SearchBot, Claude-User, GrokBot, Applebot, DuckAssistBot, YouBot, CCBot, meta-externalagent, OpenClaw, Hermes, and User-agent *.
- Hugging Bay exposes server-rendered summaries, schema.org JSON-LD, OpenAPI, MCP, answer packs, citation packs, sitemaps, llms.txt, robots.json, and bounded indexing URL batches so assistants can cite and use the platform without scraping hash routes.
- Authenticated publisher, upload, admin, import, and mirror execution endpoints are not public crawler surfaces.
- Hugging Bay does not bypass gated, private, or restricted upstream access. Hosted downloads exist only for reviewed public artifacts with manifest and hash metadata.

## Best Starting Points
- Agent discovery contract: https://huggingbay.xyz/.well-known/agent-discovery.json and https://huggingbay.xyz/api/agent-discovery
- AI crawler policy: https://huggingbay.xyz/.well-known/ai-crawler-policy.json
- AI bot allowlist and WAF guidance: https://huggingbay.xyz/.well-known/ai-bot-allowlist.json
- AI search guidance: https://huggingbay.xyz/api/ai-search
- One-call citation pack: https://huggingbay.xyz/api/citations?q=verified%20open%20AI%20registry
- Answer engine manifest: https://huggingbay.xyz/.well-known/answer-engine.json
- Answer packs: https://huggingbay.xyz/api/answers
- OpenAPI: https://huggingbay.xyz/openapi.json
- Python SDK: https://huggingbay.xyz/python-sdk, https://huggingbay.xyz/sdk/hugging_bay.py, https://huggingbay.xyz/sdk/python/release.json, and https://huggingbay.xyz/sdk/python/README.md
- MCP manifest: https://huggingbay.xyz/.well-known/mcp.json
- MCP server card: https://huggingbay.xyz/.well-known/mcp/server-card.json
- Hosted remote MCP: https://huggingbay.xyz/api/mcp
- Hosted remote MCP alias: https://huggingbay.xyz/mcp
- AI visibility status: https://huggingbay.xyz/api/ai-visibility
- Public data manifest: https://huggingbay.xyz/data/manifest.json
- Bounded catalog JSONL: https://huggingbay.xyz/api/dumps/catalog.jsonl?limit=1000
- Hosted files JSONL: https://huggingbay.xyz/api/dumps/hosted-files.jsonl?limit=1000
- Recent RSS feed: https://huggingbay.xyz/feeds/recent.xml
- Trending RSS feed: https://huggingbay.xyz/feeds/trending.xml
- Hosted mirrors RSS feed: https://huggingbay.xyz/feeds/hosted-mirrors.xml
- Reviews RSS feed: https://huggingbay.xyz/feeds/reviews.xml
- Activation loops: https://huggingbay.xyz/start and https://huggingbay.xyz/api/activation
- Hosted local models API: https://huggingbay.xyz/api/hosted-local-models?limit=100
- Community review queue: https://huggingbay.xyz/api/community/review-queue?mode=needs-evidence&hosting=actionable&limit=25
- Community review action templates: https://huggingbay.xyz/api/community/review-actions
- Agent task workflows: https://huggingbay.xyz/api/agents/tasks
- Agent briefing: https://huggingbay.xyz/api/agents/briefing
- Publisher launch kit: https://huggingbay.xyz/publishers/launch-kit and https://huggingbay.xyz/api/publishers/launch-kit
- Release with Hugging Bay workflow: https://huggingbay.xyz/api/publishers/launch-kit
- Indexing status: https://huggingbay.xyz/api/indexing/status
- IndexNow submission metadata: https://huggingbay.xyz/api/indexing/indexnow
- Agent-doc URL batch: https://huggingbay.xyz/api/indexing/urls?kind=agent-doc&limit=100
- Publisher/lab URL batch: https://huggingbay.xyz/api/indexing/urls?kind=publisher&limit=500&cursor=0
- Artifact evidence URL batch: https://huggingbay.xyz/api/indexing/urls?kind=artifact-evidence&limit=1000&cursor=0
- Artifact indexing rows with release readiness: https://huggingbay.xyz/api/indexing/urls?kind=artifact&limit=100&cursor=0
- Stable API v1 search: https://huggingbay.xyz/api/v1/search?limit=20&sort=best
- Stable API v1 hosted mirrors: https://huggingbay.xyz/api/v1/mirrors/hosted?limit=100

## Common Agent Workflows
- Resolve an upstream repo: GET https://huggingbay.xyz/api/resolve?repo=https://huggingface.co/{owner}/{repo}
- Search catalog rows: GET https://huggingbay.xyz/api/artifacts?summary=1&q=<query>&limit=20
- Hybrid semantic search: GET https://huggingbay.xyz/api/search/semantic?q=<natural_language_query>&limit=20
- Recommend by use case: GET https://huggingbay.xyz/api/recommender?useCase=rag&tool=ollama&limit=12
- Fetch artifact bundle: GET https://huggingbay.xyz/api/artifacts/{id}/agent-bundle
- Fetch artifact version provenance: GET https://huggingbay.xyz/api/artifacts/{id}/versions
- Fetch launch-ready release bundle: GET https://huggingbay.xyz/api/releases/{id} and cite https://huggingbay.xyz/releases/{id}
- Fetch release readiness checklist: GET https://huggingbay.xyz/api/releases/{id}/readiness
- Fetch normalized card markdown: GET https://huggingbay.xyz/api/artifacts/{id}/card.md
- Fetch distribution state: GET https://huggingbay.xyz/api/artifacts/{id}/distribution
- Fetch hosted download plan: GET https://huggingbay.xyz/api/artifacts/{id}/download-plan
- Fetch compact review summary: GET https://huggingbay.xyz/api/artifacts/{id}/review-summary
- Fetch community review queue: GET https://huggingbay.xyz/api/community/review-queue?mode=needs-evidence&hosting=actionable&limit=25
- Fetch review action templates before submitting evidence: GET https://huggingbay.xyz/api/community/review-actions
- Find actual hosted local-run files: GET https://huggingbay.xyz/api/hosted-local-models?limit=100
- Search by review status: GET https://huggingbay.xyz/api/artifacts?summary=1&reviewStatus=first-review&limit=25, reviewStatus=needs-evidence, reviewed, verified-run, or benchmark
- Crawl review-status artifact URL batches: GET https://huggingbay.xyz/api/indexing/urls?kind=artifact&reviewStatus=verified-run&limit=100
- List hosted files: GET https://huggingbay.xyz/api/downloadable-files?limit=100
- Fetch mirror readiness: GET https://huggingbay.xyz/api/mirror-readiness?limit=50
- Request a mirror: POST https://huggingbay.xyz/api/artifacts/{id}/mirror-request
- Operator request automation status is token-gated; public crawlers should use /api/mirror-demand and /api/mirror-readiness instead.
- Queue missing public source: POST https://huggingbay.xyz/api/source-requests
- Compare artifacts: GET https://huggingbay.xyz/api/compare?ids=<id1>,<id2>
- List publisher/lab profile URLs: GET https://huggingbay.xyz/api/indexing/urls?kind=publisher&limit=500&cursor=0
- Fetch AI visibility status: GET https://huggingbay.xyz/api/ai-visibility
- Fetch single-call agent discovery: GET https://huggingbay.xyz/api/agent-discovery or GET https://huggingbay.xyz/.well-known/agent-discovery.json
- Bulk ingest bounded catalog rows: GET https://huggingbay.xyz/api/dumps/catalog.jsonl?limit=1000&cursor=0
- Bulk ingest hosted file rows: GET https://huggingbay.xyz/api/dumps/hosted-files.jsonl?limit=1000&cursor=0
- Embed an artifact badge: GET https://huggingbay.xyz/api/badges/artifact/{id} or https://huggingbay.xyz/badges/artifact/{id}.svg
- Embed a publisher/lab badge: GET https://huggingbay.xyz/api/badges/publisher/{namespace} or https://huggingbay.xyz/badges/publisher/{namespace}.svg
- Fetch trending artifacts: GET https://huggingbay.xyz/api/trending?window=7d&limit=25
- Stable API v1 equivalents: GET https://huggingbay.xyz/api/v1/search, GET https://huggingbay.xyz/api/v1/artifacts/{id}, GET https://huggingbay.xyz/api/v1/artifacts/{id}/files, GET https://huggingbay.xyz/api/v1/artifacts/{id}/manifest, GET https://huggingbay.xyz/api/v1/compare?ids=<id1>,<id2>, GET https://huggingbay.xyz/api/v1/trending, GET https://huggingbay.xyz/api/v1/mirrors/hosted
- Stable API v1 writes: POST https://huggingbay.xyz/api/v1/mirror-requests with {"artifactId":"..."} and POST https://huggingbay.xyz/api/v1/submissions with {"repo":"https://huggingface.co/{owner}/{repo}"}

## MCP Quick Start
- Discover public remote tools: GET https://huggingbay.xyz/api/mcp or GET https://huggingbay.xyz/mcp
- List tools: curl -s https://huggingbay.xyz/api/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
- Call a public search tool: curl -s https://huggingbay.xyz/api/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_artifacts","arguments":{"q":"embedding model","limit":5}}}'
- Public hosted MCP catalog tools are read-only. Authenticated bearer-token tools can manage account saved searches and watchlist digests; publisher/admin/operator execution still uses REST routes or the downloadable stdio MCP server.
- Hosted MCP account tools: call `save_saved_search`, `list_saved_searches`, `get_saved_search_digest`, and `delete_saved_search` with `Authorization: Bearer <reader|publisher|admin token>`.
- Authenticated operator tooling can inspect recent demand, direct mirror candidates, reviewed-weight candidates, and policy-blocked rows; these controls are not public crawler surfaces.

## Crawl Rules
- Prefer canonical non-hash URLs listed in sitemap and /api/indexing/urls.
- Use limit and cursor on all catalog scans; never crawl unbounded API pages.
- Use /api/citations and /api/answers before broad fanout when answering common product questions.
- Use /api/artifacts/{id}/card.md for concise artifact facts instead of scraping the interactive UI.
- Use /api/artifacts/{id}/review-summary for compact answer-engine trust/review evidence before quoting community ratings.
- Use /api/community/review-queue before requesting fresh reviews or verified-run evidence; missing reviews are a call for evidence, not a negative quality claim.
- Cite hosted downloads only when /api/downloadable-files, /api/artifacts/{id}/download-plan, /api/artifacts/{id}/distribution, or manifest endpoints show the file is hosted by Hugging Bay.
- Do not claim Hugging Bay hosts every upstream artifact. It is a broad metadata catalog plus selective verified mirrors.