API REFERENCE

REST API and SDK documentation for programmatic access to Turbine.

§ REST API

The Turbine dashboard exposes a REST API on the same port (default 3000).

Base URL: http://localhost:3000/api

§ GET /api/status

Get current system status.

GET /api/status

Response:
{
  "rigs": [...],
  "agents": [...],
  "convoys": [...],
  "providers": {
    "claude": { "capacity": 0.73 },
    "codex": { "capacity": 0.45 },
    "gemini": { "capacity": 0.12 }
  }
}

§ GET /api/cost

Get cost analytics for a time period.

GET /api/cost?period=7d&groupBy=provider

Response:
{
  "period": "7d",
  "total": 183.24,
  "breakdown": {
    "claude": 127.84,
    "codex": 43.22,
    "gemini": 12.18
  }
}

§ GET /api/events

Stream real-time events via Server-Sent Events.

GET /api/events

Event stream:
data: {"type":"bead.complete","bead":"bd-a2f3",...}
data: {"type":"agent.status","agent":"agent-0",...}
data: {"type":"rate.warning","provider":"claude",...}

§ POST /api/config

Update configuration at runtime.

POST /api/config
Content-Type: application/json

{
  "providers.claude.rateLimit": 1500,
  "alerts.costDaily": 150
}

Response:
{ "success": true }

§ NODE.JS SDK

Install the SDK for programmatic access:

npm install @turbine/sdk

Usage

import { Turbine } from '@turbine/sdk'

const turbine = new Turbine({
  endpoint: 'http://localhost:3000'
})

// Get status
const status = await turbine.status()

// Subscribe to events
turbine.on('bead.complete', (bead) => {
  console.log('Bead completed:', bead.id)
})

// Get cost report
const cost = await turbine.cost({ period: '7d' })

§ WEBSOCKET API

Connect via WebSocket for bidirectional communication:

ws://localhost:3000/ws

// Subscribe to events
{ "type": "subscribe", "events": ["bead.*", "agent.*"] }

// Unsubscribe
{ "type": "unsubscribe", "events": ["bead.*"] }