🐭 PinkyBot API Documentation

Complete reference for all PinkyBot REST API endpoints

Base URL: or https://pinkybot.io
Authentication: API keys are configured locally in Settings. No Authorization header needed for local deployment.

🏥 Health & Status

GET /api/health

Check server status, uptime, and available models

Response: 
{
  "status": "online",
  "mode": "LIVE",
  "model": "xai/grok-4-latest",
  "codeModel": "anthropic/claude-sonnet-4-5",
  "hasXaiKey": true,
  "hasAnthropicKey": true,
  "uptime": 3600.5,
  "timestamp": "2026-02-06T07:00:00.000Z",
  "wsClients": 0
}

📋 Tasks

GET /api/tasks

Get all tasks (pending, running, completed)

Response (array): 
[{
  "id": "create-readme-install-guide",
  "name": "Create README.md install guide for new PinkyBot users",
  "assigned": "2026-02-06",
  "status": "completed",
  "updated": "2026-02-06",
  "priority": "P2",
  "notes": "6.7KB with installation guide, features, pricing, troubleshooting",
  "sort_order": 0
}]

POST /api/tasks

Create, update, or delete tasks

Create Task: 
{
  "action": "create",
  "name": "My task",
  "status": "pending",
  "priority": "P1",
  "notes": "Task description"
}
Update Status: 
{
  "action": "update_status",
  "taskName": "My task",
  "newStatus": "running"
}
Delete Task: 
{
  "action": "delete",
  "name": "My task"
}

📊 Activity & Logging

GET /api/activity

Get heartbeat activity log (last 100 entries)

Response: 
{
  "heartbeats": [{
    "timestamp": 1707190800000,
    "activity": "Heartbeat #129: Completed 2 P2 tasks...",
    "lagMs": 0,
    "tokens": 2100,
    "exec": 12
  }],
  "heartbeatCount": 129,
  "lastUpdated": "2026-02-06T07:00:00.000Z"
}

💻 System Health

GET /api/system/metrics

Get live CPU, memory, disk usage

Returns system resource metrics in real-time

🔐 Authentication

For self-hosted PinkyBot, no API key is required — the server is local and assumes trusted access.
For cloud-hosted instances, API keys are managed in Settings > API Configuration.

⚡ Rate Limits

Local deployment: Unlimited
Cloud deployment: Pro tier gets 10,000 req/hour, Enterprise gets 100,000 req/hour

❌ Error Handling

All responses return HTTP status codes:

📚 Examples

1. Check if PinkyBot is online

curl /api/health

2. Get all pending tasks

curl /api/tasks | jq '.[] | select(.status=="pending")'

3. Create a new task

curl -X POST /api/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "create",
    "name": "Write documentation",
    "priority": "P1",
    "notes": "Create user guide"
  }'

4. Update task status to running

curl -X POST /api/tasks \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "update_status",
    "taskName": "Write documentation",
    "newStatus": "running"
  }'

5. View recent activity

curl /api/activity | jq '.heartbeats | last'

💬 Support

For API questions, feature requests, or bug reports:

PinkyBot API © 2026 | Built by Ken & Pinky 🐭