API Reference

Programmatic access to your Styrby data. Available on the Pro or Growth tier.

Authentication

Generate an API key in the dashboard under Settings > API Keys. Pass it as a Bearer token in the Authorization header.

Authorization: Bearer styrby_abc123...

API keys are prefixed with styrby_. They are hashed with bcrypt (cost factor 12) before storage. Styrby cannot retrieve your key after creation. Store it securely. Keys can optionally expire; set an expiration in days when creating the key.

Base URL

https://styrbyapp.com/api/v1

GET /sessions

Returns a paginated list of your sessions, newest first. Archived sessions are excluded by default.

Query Parameters

curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/sessions?agent_type=claude&limit=5"

# Response
{
  "sessions": [
    {
      "id": "ses_8f3k2m9x",
      "agent_type": "claude",
      "model": "claude-sonnet-4-20250514",
      "title": "Refactor auth module",
      "status": "stopped",
      "total_input_tokens": 12840,
      "total_output_tokens": 3210,
      "total_cache_tokens": 8400,
      "total_cost_usd": 0.042,
      "started_at": "2026-03-22T14:30:00Z",
      "ended_at": "2026-03-22T14:45:12Z",
      "created_at": "2026-03-22T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 5,
    "offset": 0,
    "hasMore": true
  }
}

GET /costs

Returns aggregated cost data for a time period. Choose daily (last 30 days), weekly (last 12 weeks), or monthly (last 12 months) aggregation.

Query Parameters

curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/costs?period=daily"

# Response
{
  "summary": {
    "period": "daily",
    "totalCostUsd": 18.73,
    "totalInputTokens": 284000,
    "totalOutputTokens": 62000,
    "totalCacheTokens": 190000,
    "sessionCount": 47
  },
  "breakdown": [
    {
      "date": "2026-03-22",
      "costUsd": 2.14,
      "inputTokens": 34000,
      "outputTokens": 8000,
      "cacheTokens": 22000
    }
  ]
}

GET /costs/breakdown

Returns cost breakdown grouped by agent type for a trailing window.

Query Parameters

curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/costs/breakdown?days=30"

# Response
{
  "breakdown": [
    {
      "agentType": "claude",
      "costUsd": 15.42,
      "inputTokens": 220000,
      "outputTokens": 48000,
      "cacheTokens": 160000,
      "sessionCount": 38,
      "percentage": 82.3
    },
    {
      "agentType": "codex",
      "costUsd": 3.31,
      "inputTokens": 64000,
      "outputTokens": 14000,
      "cacheTokens": 30000,
      "sessionCount": 9,
      "percentage": 17.7
    }
  ],
  "total": {
    "costUsd": 18.73,
    "inputTokens": 284000,
    "outputTokens": 62000,
    "cacheTokens": 190000,
    "sessionCount": 47
  }
}

GET /machines

Returns all paired machines for your account.

Query Parameters

curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/machines"

# Response
{
  "machines": [
    {
      "id": "mch_abc123",
      "name": "macbook-pro",
      "platform": "darwin",
      "hostname": "macbook-pro.local",
      "cliVersion": "0.1.0-beta.7",
      "isOnline": true,
      "lastSeenAt": "2026-03-22T15:42:00Z",
      "createdAt": "2026-03-10T09:00:00Z"
    }
  ],
  "count": 1
}

GET /sessions/:id

Returns a single session by UUID. The path parameter must be a valid UUID; otherwise the endpoint returns 400.

curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/sessions/8f3k2m9x-1234-5678-9abc-def012345678"

# Errors
# 400 { "error": "Invalid session ID" }
# 404 { "error": "Session not found" }

GET /sessions/:id/messages

Lists messages for a session. Message bodies are end-to-end encrypted and returned as ciphertext. Decryption requires the per-machine private key, so this endpoint is mainly useful for metadata, archival, and client-side decryption pipelines.

Query Parameters

GET / POST /sessions/:id/checkpoints

Lists or creates named checkpoints inside a session timeline. POST requires the Pro plan and rejects names longer than 80 characters or outside the [a-zA-Z0-9 \-_.] character class. Names must be unique within a session.

# List
curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/sessions/<id>/checkpoints"

# Create
curl -X POST -H "Authorization: Bearer styrby_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "before-refactor",
    "description": "auth module rewrite, message 142",
    "messageSequenceNumber": 142
  }' \
  "https://styrbyapp.com/api/v1/sessions/<id>/checkpoints"

# Errors
# 400 { "error": <Zod validation message> }
# 403 { "error": "Pro plan required" }
# 409 { "error": "Checkpoint name already exists" }

GET /costs/export

Streams raw cost records as CSV for accounting and reconciliation. Pro and Growth only. Throttled to 1 request per hour per API key (export is expensive); the standard 100 req/min ceiling still applies for everything else.

curl -H "Authorization: Bearer styrby_abc123" \
  "https://styrbyapp.com/api/v1/costs/export?days=90" \
  -o styrby-costs.csv

# Response: text/csv with header
# date, session_id, agent_type, model, input_tokens,
# output_tokens, cache_tokens, cost_usd

# Errors
# 403 { "error": "Pro plan required" }
# 429 { "error": "RATE_LIMITED" }

Rate Limits

Error Codes

All error responses use the same shape:

{
  "error": "Rate limit exceeded. Try again in 42 seconds."
}