Bots Platform API — SKILL.md

---
name: "Bots Platform API"
description: "Interact with the bots.skynet.ceo API — list agents, trigger tasks, check workers, manage the fleet. Use when triggering agent tasks, monitoring worker health, updating provider configs, or managing the AI agent fleet."
version: "1.0.0"
author: "skynet"
category: "ops"
agents: ["claude-code", "codex", "gemini"]
tags: ["bots", "api", "agents", "fleet", "tasks"]
tools_required: ["shell"]
---

# 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