Bots Platform API

# Bots Platform API ## When to use Use this skill when you need to interact with the bots platform — list agents, trigger agent tasks, check worker health, or manage the AI agent fleet. ## Prerequisites - `BOTS_SECRET_KEY` set in environment (from `~/dev/projects/bots/.env`) - Network access to `https://bots.skynet.ceo` ## Instructions ### Authentication All API calls require a Bearer token: ```bash source ~/dev/projects/bots/.env AUTH="Authorization: Bearer $BOTS_SECRET_KEY" BASE="https://bots.skynet.ceo" ``` ### List all agents ```bash curl -s -H "$AUTH" "$BASE/api/agents" | jq '.[] | {id, name, fleet_type, provider}' ``` ### Get agent details ```bash curl -s -H "$AUTH" "$BASE/api/agents/<agent-id>" | jq . ``` ### Trigger an agent task ```bash curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \ "$BASE/api/agents/<agent-id>/tasks" \ -d '{ "prompt": "Write a blog post about containerization best practices", "stage": "write" }' ``` The `stage` field is optional. If omitted, the agent runs its default pipeline. Common stages: `topic_select`, `write`, `image_gen`, `publish`. ### Check worker fleet health ```bash curl -s -H "$AUTH" "$BASE/api/usage/workers" | jq . ``` Returns health status for all worker nodes: - **dev1**: `https://worker-dev1.skynet.ceo` (Linux, claude/codex/gemini) - **bots-mac**: `https://worker-bots.skynet.ceo` (Mac, claude/codex/gemini/kimi + browser) - **jarvis-mac**: `https://worker-jarvis.skynet.ceo` (Mac, claude/codex/gemini/kimi + browser) - **spark**: `https://worker-spark.skynet.ceo` (Linux DGX, claude/codex/gemini/kimi) ### List available providers ```bash curl -s -H "$AUTH" "$BASE/api/providers" | jq . ``` Returns the fleet/provider/model matrix showing which CLI tools are available on which nodes. ### Check API subscription caps ```bash curl -s -H "$AUTH" "$BASE/api/caps" | jq . ``` ### Update agent provider config ```bash curl -s -X PATCH -H "$AUTH" -H "Content-Type: application/json" \ "$BASE/api/agents/<agent-id>/provider-config" \ -d '{ "fleet_type": "linux-content", "provider": "gemini", "model": "gemini-2.5-flash" }' ``` ### Health check ```bash curl -s "$BASE/health" # Returns: {"status": "healthy", ...} ``` Note: `/health` is the only unauthenticated public endpoint. ### Common patterns **Trigger tasks for all content agents:** ```bash source ~/dev/projects/bots/.env for agent_id in $(curl -s -H "Authorization: Bearer $BOTS_SECRET_KEY" "$BASE/api/agents" | jq -r '.[] | select(.fleet_type=="linux-content") | .id'); do echo "Triggering $agent_id..." curl -s -X POST -H "Authorization: Bearer $BOTS_SECRET_KEY" -H "Content-Type: application/json" \ "$BASE/api/agents/$agent_id/tasks" \ -d '{"prompt": "Write your next blog post"}' sleep 2 done ``` **Direct Cloud Run access (bypassing CF Worker):** ```bash OIDC=$(gcloud auth print-identity-token) curl -s \ -H "Authorization: Bearer $OIDC" \ -H "X-Original-Authorization: Bearer $BOTS_SECRET_KEY" \ "https://bots-platform-prod-932755426011.northamerica-northeast1.run.app/api/agents" ``` ## Troubleshooting - **401 Unauthorized**: Check `BOTS_SECRET_KEY` is set correctly. Re-source `.env`. - **1 agent returned**: Cold start race condition. Wait 10s and retry. - **Task stuck**: Check worker health first. If workers are down, tasks queue but don't execute. - **504 Gateway Timeout**: CF Worker proxy has 30s timeout. Large responses may need direct Cloud Run access. ## References - Platform source: `~/dev/projects/bots/` - API routes: `src/bots/api/` - Worker server: `src/bots/worker/server.py` - Public URL: https://bots.skynet.ceo