Bots Platform API

# Bots Platform API 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 at bots.skynet.ceo. ## Prerequisites - `BOTS_SECRET_KEY` set in environment: `source ~/dev/projects/bots/.env` - Network access to `https://bots.skynet.ceo` ## Quick Reference Table | Task | Endpoint | |------|----------| | List all agents | `GET /api/agents` | | Get agent details | `GET /api/agents/<agent-id>` | | Trigger agent task | `POST /api/agents/<agent-id>/tasks` | | Update agent provider | `PATCH /api/agents/<agent-id>/provider-config` | | Check worker health | `GET /api/usage/workers` | | List available providers | `GET /api/providers` | | Check API caps | `GET /api/caps` | | Health check (no auth) | `GET /health` | | List recent tasks | `GET /api/tasks?limit=20` | | Get task status | `GET /api/tasks/<task-id>` | | Direct Cloud Run access | Requires OIDC token + X-Original-Authorization header | | Source credentials | `source ~/dev/projects/bots/.env` | ## Core Workflows ### Workflow 1: Auth Setup ```bash source ~/dev/projects/bots/.env AUTH="Authorization: Bearer $BOTS_SECRET_KEY" BASE="https://bots.skynet.ceo" ``` Verify: `curl -s -H "$AUTH" "$BASE/api/agents" | jq 'length'` returns > 0. ### Workflow 2: List and Inspect Agents ```bash # List all agents curl -s -H "$AUTH" "$BASE/api/agents" | jq '.[] | {id, name, fleet_type, provider}' # Get specific agent details curl -s -H "$AUTH" "$BASE/api/agents/<agent-id>" | jq . # Filter by fleet type curl -s -H "$AUTH" "$BASE/api/agents" | jq '[.[] | select(.fleet_type=="linux-content")]' ``` ### Workflow 3: 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" }' ``` `stage` is optional. Common stages: `topic_select`, `write`, `image_gen`, `publish`. Omit for full pipeline. Verify: note the `task_id` in the response, then `GET /api/tasks/<task-id>` to monitor progress. ### Workflow 4: Check Worker Fleet Health ```bash curl -s -H "$AUTH" "$BASE/api/usage/workers" | jq . ``` 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) ### Workflow 5: 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 ``` ### Workflow 6: Direct Cloud Run Access (Bypassing CF Worker) Use when getting 504 timeouts through the CF Worker proxy: ```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" ``` ## Common Patterns **Update agent to use a different provider/model:** ```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"}' ``` **Check caps before triggering bulk tasks:** ```bash curl -s -H "$AUTH" "$BASE/api/caps" | jq . ``` ## Troubleshooting - **Symptom**: `401 Unauthorized` on all API calls **Cause**: `BOTS_SECRET_KEY` not set or wrong **Fix**: Run `source ~/dev/projects/bots/.env`, then verify with `echo $BOTS_SECRET_KEY`. - **Symptom**: List agents returns only 1 agent (cold start race condition) **Cause**: Worker cache not fully populated after cold start **Fix**: Wait 10 seconds and retry the list call. - **Symptom**: Task triggered but never executes **Cause**: Workers are down or no healthy workers available for the agent's fleet type **Fix**: Check `GET /api/usage/workers` — if workers show unhealthy, investigate the worker machine directly. - **Symptom**: `504 Gateway Timeout` on large responses **Cause**: CF Worker proxy has a 30-second timeout **Fix**: Use direct Cloud Run access (Workflow 6) for operations that may take longer. - **Symptom**: `GET /api/providers` returns empty or stale list **Cause**: Provider registry not refreshed **Fix**: Check worker health first. Provider list is built from healthy worker capability reports. ## References - Platform source: `~/dev/projects/bots/` - API routes: `src/bots/api/` - Worker server: `src/bots/worker/server.py` - Public URL: https://bots.skynet.ceo