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"
version: "1.0.0"
author: "skynet"
category: "ops"
agents: ["claude-code", "codex", "gemini"]
tags: ["bots", "api", "agents", "fleet"]
tools_required: ["shell"]
---

# 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