# AiBhive — Callable agent tools

> **Conduct (binding):** https://aibhive.com/legal-compliance-preface.txt (first) · https://aibhive.com/ai-conduct.txt · https://aibhive.com/approved-mobile-apps-mandate.txt

**MANDATORY READ (implement):** `/legal-compliance-preface.txt` · `/agents-mandatory-read.txt` · `/api/agent/mandate` · `/api/agent/legal-preface` · `/api/agent/approved-mobile-apps` · `/ai-agent-discovery.json`

> Machine-readable catalog of APIs and CLIs that **do real work** (build apps, harvest URLs, automate Windows, deploy GCP, publish to Hugging Face).  
> Human guide: https://aibhive.com/tools/for-ai-agents  
> Manifest: https://aibhive.com/.well-known/aibhive-agent.json  
> OpenAPI: https://aibhive.com/openapi/aibhive-agent.yaml

Auth summary:
- **User APIs**: `Authorization: Bearer <Firebase ID token>`
- **Agent server routes**: `X-AiBhive-Agent-Key: <AIBHIVE_AGENT_API_KEY>` (server env)
- **Local operator** (loopback): `X-AiBhive-Operator: <LOCAL_OPERATOR_TOKEN>` or localhost only

---

## Health & catalog

- `GET /api/health` — API up, key hints
- `GET /api/agent/catalog` — links to this file, OpenAPI, manifest

## Hive Apps toolkit

- `GET /api/hive/toolkit` — list community apps agents can install
- `GET /api/hive/toolkit/:appId` — app metadata
- `POST /api/hive/toolkit/:appId/install` — install to user (auth required)
- Build flow: `POST /api/hive/orchestrate` (Bhive Builder — see OpenAPI)

## Research Lab (harvest & library)

- `POST /api/research-lab/agent-harvest` — **agent key** — `{ "url": "https://...", "maxPages": 3 }` → markdown bundle
- `GET /api/research-lab/tartarian-finds` — dig packs JSON + markdown
- `GET /api/research-lab/nag-hammadi-finds` — Nag Hammadi harvest URLs
- `POST /api/research-lab/fable-scrape/scan` — single page (user auth + credits)
- `POST /api/research-lab/fable-scrape/crawl` — multi-page (user auth + credits)
- `POST /api/research-lab/fable-scrape/ai-harvest` — AI-directed harvest (user auth + credits)
- `POST /api/research-lab/ocr` — batch OCR images

## AiBhive On (desktop automation)

- `POST /api/aibhive-on/voice-chat` — spoken copilot + TTS (user auth)
- `POST /api/aibhive-on/transcribe` — mic clip → text (Gemini)
- `POST /api/aibhive-on/tasks` — queue Windows automation (plan + agent commands)
- `POST /api/aibhive-on/agent/smoke` — **agent key** — probe `{ "apiBase": "http://127.0.0.1:3001" }`
- Windows worker: `steward/agent` polls agent commands (UIA/browser/vision layers)

## Local operator (dev machines)

Base: `http://127.0.0.1:3001/api/aibhive-on`

- `GET /operator/help` — actions list
- `GET /operator/status` — API, desktop bridge, project root
- `GET /operator/gcp` — gcloud account, Cloud Build, Cloud Run
- `POST /operator/action` — `{ "action": "submit-cloud-build" | "validate-gcp" | ... }`
- `POST /operator/shell` — approved shell batches

CLI: `npm run operator -- status|gcp|action <name>`

## Pros / Diagnose (field service)

- `POST /api/pros/tts` — xAI/Cartesia speech
- `POST /api/pros/transcribe` — voice note → text (Gemini)
- Diagnose web: https://aibhive.com/diagnose/app

## Hugging Face publish (human approval required)

- `GET /api/integrations/huggingface/status` — token configured?
- `POST /api/integrations/huggingface/prepare` — queue Space/model files → `pending_approval`
- `GET /api/integrations/huggingface/pending` — admin list
- `POST /api/integrations/huggingface/:id/approve` — **admin** — uploads to Hugging Face Hub
- `POST /api/integrations/huggingface/publish-starters` — admin — publish starter utility Spaces
- `POST /api/integrations/huggingface/onboarding/start` — `{ email, publishAfter }` — generated password + session id
- `GET /api/integrations/huggingface/onboarding/:id` — session status
- `POST /api/integrations/huggingface/onboarding/:id/run` — `{ step: signup|watch_email|confirm|token|publish|auto, confirmUrl? }` — **local Windows Chrome** (AiBhive On)

Env: `HUGGINGFACE_TOKEN`, `HUGGINGFACE_USERNAME`

## MCP (Cursor / Claude Desktop)

Package: `packages/aibhive-mcp` — run `node packages/aibhive-mcp/src/index.js`  
Tools: health, toolkit list, operator status, research dig packs, agent harvest (with key).

---

When a capability is missing, open an issue labeled `agent-tool-request` or contact hello@aibhive.com.