API Reference

OpenAPI Specification Download the OpenAPI 3.0 spec for code generation and API clients

The TailTrace API provides cloud-based design system configuration and drift analytics.

Base URL

https://api.tailtrace.dev

Authentication

All API requests require a Bearer token:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.tailtrace.dev/api/workspaces

Get your API token from the dashboard.

Endpoints

Workspaces

List Workspaces

GET /api/workspaces

Returns all workspaces you have access to.

Response:

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "My Team",
      "slug": "my-team",
      "role": "owner"
    }
  ]
}

Create Workspace

POST /api/workspaces

Request:

{
  "name": "New Workspace",
  "slug": "new-workspace"
}

Configs

List Configs

GET /api/configs?workspace_id=ws_abc123

Response:

{
  "configs": [
    {
      "id": "cfg_xyz789",
      "name": "Production",
      "config": { "colors": {...} },
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Config

GET /api/configs/:id

Use this endpoint in your extensions to fetch cloud-synced configuration.

Create Config

POST /api/configs

Request:

{
  "workspace_id": "ws_abc123",
  "name": "Production",
  "config": {
    "colors": {
      "primary": "#3b82f6"
    },
    "deltaEThreshold": 2.3
  }
}

Update Config

PUT /api/configs/:id

Drift Reports

Submit Drift Report

POST /api/drift

Request:

{
  "workspace_id": "ws_abc123",
  "config_id": "cfg_xyz789",
  "url": "https://example.com/page",
  "stats": {
    "total": 24,
    "exact": 18,
    "fuzzy": 4,
    "none": 2,
    "processingTime": 12.5
  }
}

Get Drift Summary

GET /api/drift/summary?workspace_id=ws_abc123

Returns aggregated drift statistics for the last 30 days.

Response:

{
  "summary": {
    "totalReports": 156,
    "totalStyles": 3744,
    "exactMatches": 3200,
    "fuzzyMatches": 400,
    "noMatches": 144,
    "complianceRate": 96
  }
}

Rate Limits

Tier	Requests/minute
Free	60
Pro	600
Enterprise	Unlimited

Error Responses

{
  "error": "Unauthorized"
}

Status	Meaning
400	Bad request
401	Unauthorized (invalid token)
403	Forbidden (requires Pro)
404	Not found
429	Rate limited
500	Server error

SDKs

Coming soon:

@tailtrace/sdk - JavaScript/TypeScript
tailtrace-py - Python