API Reference

The SignalSmith REST API provides programmatic access to all platform resources. Use it to manage warehouses, models, destinations, syncs, audiences, identity graphs, journeys, events, and more.

Base URL

All API requests are made to your SignalSmith instance:

https://your-instance.signalsmith.io/api/v1

The API is versioned via the URL path. The current version is v1.

Request Format

• All request bodies must be JSON with Content-Type: application/json
• All responses are JSON with Content-Type: application/json
• Resource paths follow the pattern /api/v1/workspaces/{workspaceId}/{resource}
• Timestamps are ISO 8601 format (e.g., 2024-01-15T09:30:00Z)
• IDs are UUIDs (e.g., 550e8400-e29b-41d4-a716-446655440000)

Authentication

Every request requires two headers:

Authorization: Bearer <token>
X-Workspace-ID: <workspace-id>

The Authorization header accepts either a Firebase ID token (for browser/UI clients) or an API key (for server-to-server integrations). See Authentication for details.

Pagination

List endpoints that return large collections support pagination via query parameters:

Paginated responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 142
  }
}

Rate Limiting

API requests are rate-limited per workspace:

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Error Format

Error responses use a consistent JSON structure:

{
  "error": "human-readable error message"
}

HTTP Status Codes

Common Response Patterns

Successful Deletion

{
  "status": "deleted"
}

Single Resource

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "...",
  "name": "...",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

List of Resources

Most list endpoints return a JSON array directly:

[
  { "id": "...", "name": "..." },
  { "id": "...", "name": "..." }
]

Resources