API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. You can find your API key in your project settings.

Authorization: Bearer sb_your_api_key_here

API keys start with sb_ and are unique to each project.

Base URL

http://status-blocks.com/api

Send Event

Send a single event to your project. Events are the building blocks for all metric calculations.

POST /api/events

Request Body

Field	Type	Required	Description
`event`	string	Required	Event name, max 100 characters
`user_id`	string	Optional	Unique user identifier, max 255 characters
`user_email`	string	Optional	User's email address
`user_name`	string	Optional	User's display name, max 255 characters
`value`	number	Optional	Numeric value (e.g. payment amount)
`metadata`	object	Optional	Key-value pairs for filtering and context

Example Request

curl -X POST http://status-blocks.com/api/events \
  -H "Authorization: Bearer sb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "user_signup",
    "user_id": "123",
    "user_email": "john@example.com",
    "metadata": {
      "plan": "starter",
      "source": "organic"
    }
  }'

Response

201 Created

{
  "success": true,
  "event_id": "9e4b2f1a-3c5d-4e6f-8a7b-1c2d3e4f5a6b"
}

Batch Events

Send up to 100 events in a single request for better performance.

POST /api/events/batch

Request Body

Field	Type	Required	Description
`events`	array	Required	Array of event objects (max 100). Each object has the same fields as the single event endpoint.

Example Request

curl -X POST http://status-blocks.com/api/events/batch \
  -H "Authorization: Bearer sb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event": "user_signup",
        "user_id": "1",
        "user_email": "alice@example.com"
      },
      {
        "event": "subscription_payment",
        "user_id": "1",
        "value": 29.00,
        "metadata": { "period": "monthly", "plan": "starter" }
      }
    ]
  }'

Response

201 Created

{
  "success": true,
  "created_count": 2,
  "event_ids": [
    "9e4b2f1a-3c5d-4e6f-8a7b-1c2d3e4f5a6b",
    "8d3a1e0b-2b4c-3d5e-7f6a-0b1c2d3e4f5a"
  ]
}

Metric Definitions

Manage your project's metric definitions via the API.

GET /api/metrics/definitions

List all metric definitions for your project.

POST /api/metrics/definitions

Create a new metric definition.

GET /api/metrics/definitions/{'{uuid}'}

Get a single metric definition by UUID.

PUT /api/metrics/definitions/{'{uuid}'}

Update an existing metric definition.

DELETE /api/metrics/definitions/{'{uuid}'}

Delete a metric definition.

GET /api/metrics/templates

List available metric template packs (SaaS, E-commerce, API).

POST /api/metrics/templates/apply

Apply a template pack to your project, creating all its metric definitions.

Metric Values

Read computed metric values and historical data.

GET /api/metrics/values

Get all current metric values for your project.

GET /api/metrics/values/{'{slug}'}

Get the current value for a specific metric.

GET /api/metrics/values/{'{slug}'}/history

Get historical daily values for a metric. Useful for building charts.

POST /api/metrics/values/{'{slug}'}/recalculate

Trigger a recalculation for a specific metric.

Error Handling

The API uses standard HTTP status codes and returns JSON error responses.

Status	Meaning	Description
200	OK	Request successful (GET requests)
201	Created	Resource created successfully
401	Unauthorized	Missing or invalid API key
422	Validation Error	Request body validation failed
500	Server Error	Something went wrong on our end

Error Response Format

// 401 Unauthorized
{
  "message": "Invalid API key."
}

// 422 Validation Error
{
  "message": "The event field is required.",
  "errors": {
    "event": ["The event field is required."]
  }
}

Code Examples

Integrate Status Blocks into your application using any language.

PHP / Laravel

<?php

use Illuminate\Support\Facades\Http;

class StatusBlocksService
{
    public function __construct(
        private string $apiKey,
        private string $baseUrl = 'http://status-blocks.com/api'
    ) {}

    public function track(
        string $event,
        ?string $userId = null,
        ?string $userEmail = null,
        ?float $value = null,
        ?array $metadata = null
    ): void {
        Http::withToken($this->apiKey)
            ->timeout(5)
            ->post("{$this->baseUrl}/events", array_filter([
                'event' => $event,
                'user_id' => $userId,
                'user_email' => $userEmail,
                'value' => $value,
                'metadata' => $metadata,
            ]));
    }
}

// Usage
$tracker = new StatusBlocksService('sb_your_api_key');
$tracker->track('user_signup', userId: '123', userEmail: 'john@example.com');
$tracker->track('subscription_payment', userId: '123', value: 29.00, metadata: [
    'period' => 'monthly',
    'plan' => 'starter',
]);

JavaScript / Node.js

class StatusBlocks {
  constructor(apiKey, baseUrl = 'http://status-blocks.com/api') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async track(event, { userId, userEmail, value, metadata } = {}) {
    const body = { event };
    if (userId) body.user_id = userId;
    if (userEmail) body.user_email = userEmail;
    if (value !== undefined) body.value = value;
    if (metadata) body.metadata = metadata;

    await fetch(`${this.baseUrl}/events`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    });
  }
}

// Usage
const tracker = new StatusBlocks('sb_your_api_key');
await tracker.track('user_signup', {
  userId: '123',
  userEmail: 'john@example.com',
});
await tracker.track('subscription_payment', {
  userId: '123',
  value: 29.00,
  metadata: { period: 'monthly', plan: 'starter' },
});

Python

import requests

class StatusBlocks:
    def __init__(self, api_key, base_url='http://status-blocks.com/api'):
        self.api_key = api_key
        self.base_url = base_url

    def track(self, event, user_id=None, user_email=None, value=None, metadata=None):
        payload = {'event': event}
        if user_id: payload['user_id'] = user_id
        if user_email: payload['user_email'] = user_email
        if value is not None: payload['value'] = value
        if metadata: payload['metadata'] = metadata

        requests.post(
            f'{self.base_url}/events',
            json=payload,
            headers={'Authorization': f'Bearer {self.api_key}'},
            timeout=5,
        )

# Usage
tracker = StatusBlocks('sb_your_api_key')
tracker.track('user_signup', user_id='123', user_email='john@example.com')
tracker.track('subscription_payment', user_id='123', value=29.00, metadata={
    'period': 'monthly',
    'plan': 'starter',
})

cURL

# Send a single event
curl -X POST http://status-blocks.com/api/events \
  -H "Authorization: Bearer sb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"event": "user_signup", "user_id": "123", "user_email": "john@example.com"}'

# Send batch events
curl -X POST http://status-blocks.com/api/events/batch \
  -H "Authorization: Bearer sb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"event": "user_signup", "user_id": "1"}, {"event": "user_login", "user_id": "1"}]}'

# Get metric values
curl http://status-blocks.com/api/metrics/values \
  -H "Authorization: Bearer sb_your_api_key"

Best Practices

🔥

Fire and forget

Don't let tracking failures affect your application. Wrap calls in try/catch and use timeouts.

📦

Use batch for bulk imports

When importing historical data or sending many events at once, use the batch endpoint (up to 100 events per request).

🏷️

Include metadata

Use metadata for filtering and segmentation. For example, include period and plan on payment events.

👤

Always include user_id

Including a user_id enables user tracking, active user metrics, and per-user event history.

Ready to start tracking?