API Reference

Documentation

Send metrics with a clean REST API, query time-series data, and export to CSV.

Getting Started

Create an API key, send your first point to `/v1/ingest`, then view it in your dashboard.

1. Create account

2. Create API key

Generate a key with at least `write` scope.

3. Ingest data

POST JSON to `/v1/ingest` and check your chart.

Quick Start

Send your first metric with one curl command:

terminal

curl -X POST https://api.statflow.dev/v1/ingest 
  -H "Authorization: Bearer sf_your_key_here" 
  -H "Content-Type: application/json" 
  -d '{"stat":"my_first_metric","value":1,"type":"counter"}'

Authentication

All API requests use a Bearer token in the `Authorization` header.

Authorization: Bearer sf_your_api_key

API Keys

Create and manage API keys in the dashboard. Use `read` and `write` scopes to limit access.

POST/v1/auth/api-keys

Create key

GET/v1/auth/api-keys

List keys

DELETE/v1/auth/api-keys/{id}

Revoke key

API Endpoints

Base URL: https://api.statflow.dev

POST/v1/ingest

Ingest one metric data point (counter or value).

{"stat":"page.views","value":1,"type":"counter"}

POST/v1/ingest/batch

Ingest up to 1000 data points in a single request.

{"items":[{"stat":"page.views","value":1,"type":"counter"}]}

GET/v1/stats

List stats in your account.

GET/v1/stats/{id}/data

Fetch time-series data for one stat.

GET/v1/stats/{id}/export?format=csv

Export stat data as CSV.

Alerts

Configure threshold, delta, and deadman alerts from the dashboard.

Dashboards

Build dashboards, share public links, and embed charts.

Stats Management

Time-Series Queries

Use `GET /v1/stats/{id}/data` with `from`, `to`, and `resolution`.

CSV Export

Use `GET /v1/stats/{id}/export?format=csv` to export data.

Annotations

Add timeline notes for deployments, incidents, and changes with `POST /v1/annotations`.

Data Import

Import historical data from StatHat in Dashboard Import using your StatHat access token.

API endpoints: /v1/import/stathat and /v1/import/stathat/status.

REST API Usage Notes

Existing integrations that send HTTP JSON requests can switch to StatFlow by targeting the endpoints above and sending Bearer auth.

terminal

curl -X POST https://api.statflow.dev/v1/ingest 
  -H "Authorization: Bearer sf_YOUR_KEY" 
  -H "Content-Type: application/json" 
  -d '{"stat":"requests.total","value":1,"type":"counter"}'

Plans & Billing

Free to start. Upgrade when you need more stats, data points, and retention.

Client Libraries

Use any HTTP client or SDK that can send JSON to the REST endpoints above.