HTTP API¶
Beta
This API is a beta version. Endpoints, parameters and responses can change without notice.
The Tipspeed HTTP API is a read-only interface to the same analytics engine as the application. It is in closed beta, with access granted per user.
API key¶
An API key is created on the profile page, with Create API key. The key is displayed only once and must be stored securely. The key is personal: requests made with it act on behalf of its owner, so it must not be shared. It can be revoked from the same page at any time. A revoked key stops working immediately.
Every request carries the key as a bearer token:
curl -H "Authorization: Bearer $TIPSPEED_API_KEY" \
https://v2.tipspeed.com/api/beta/projects/
Coding agents¶
A coding agent (Mistral, Claude Code, Cursor, …) is most effective when it works from the machine-readable contract rather than from this page. The schema is served with the same key as the data. The following instruction can be given to the agent:
Fetch the Tipspeed API contract before writing any code:
curl -H "Authorization: Bearer $TIPSPEED_API_KEY" https://v2.tipspeed.com/api/beta/openapi.json
Then call GET /api/beta/catalogue/ for the metric keys and signal names.
The key must not appear in the prompt or in the code. It should be stored in a password manager and exposed to the
project as the TIPSPEED_API_KEY environment variable, typically from a .env file listed in .gitignore so that
it is never committed. The agent then refers to the variable, and the key itself is never pasted into the
conversation.
The served schema is always current, so no local copy needs to be kept in sync. A static copy is also available: download the OpenAPI schema.
Operations¶
| Operation | Description |
|---|---|
GET /api/beta/projects/ |
The projects accessible to the key's user, with their date ranges. This is the first call: it returns the team_slug and project_slug required by every other call. |
GET /api/beta/catalogue/ |
Every available metric: key, unit, aggregation, formula, dependencies, and bin_width (a non-null value means the metric can be binned). |
GET /api/beta/projects/{team}/{project}/query |
Any metric, over any combination of the turbine, period and bin dimensions, optionally filtered by the value of a signal. |
GET /api/beta/projects/{team}/{project}/turbines |
One row per turbine: static attributes, plus any requested metrics joined to each row. |
GET /api/beta/projects/{team}/{project}/energy-chain-summary |
The gross-to-net energy waterfall for a date range. |
Queries¶
/query accepts an explicit list of metric keys and three independent dimension controls. Every registered metric
supports by_turbine and period. A metric can also be used as bin_by when the catalogue gives it a non-null
bin_width. In the examples below, $BASE stands for https://v2.tipspeed.com.
# farm production and performance ratio, month by month
curl -H "Authorization: Bearer $TIPSPEED_API_KEY" \
"$BASE/api/beta/projects/acme/northfield/query?metrics=actual_100pct_avail_energy,performance_ratio&period=1mo"
# per-turbine production, binned by wind speed
curl -H "Authorization: Bearer $TIPSPEED_API_KEY" \
"$BASE/api/beta/projects/acme/northfield/query?metrics=actual_100pct_avail_energy&by_turbine=true&bin_by=wind_speed"
# only the rows where the modelled wind speed was between 8 and 12 m/s
curl -H "Authorization: Bearer $TIPSPEED_API_KEY" \
"$BASE/api/beta/projects/acme/northfield/query?metrics=actual_100pct_avail_energy&filter_by=wind_speed_optimized_model&filter_min=8&filter_max=12"
filter_by takes a signal name, not a metric key: signals and metrics are separate namespaces. The catalogue
lists the valid signal names under signals and the metric keys under metrics. For a source signal, such as
wind_speed_optimized_model above, the column and model fields of the catalogue entry identify the underlying
quantity and model. They indicate the unit of the filter bounds: m/s in this example.
Each row contains time, turbine and bin, which are null for any dimension not requested, and a values object
keyed by metric key.
A metric that is not part of a project's delivered results is returned with null values. Used as bin_by or
filter_by, it is rejected with a 400 error: "Not available on this project".
period takes one of the values 10min, 1h, 1d, 1mo, 1y and all. The default is 1d: a query without
period returns one row per day. period=all returns a single row totalling the whole date range.
time labels each period in UTC: 2026-01-01T10:20Z for 10min; 2026-01-01T10:00Z for 1h; 2026-01-01,
2026-01 and 2026 for 1d, 1mo and 1y; null for all. A 10min label is the timestamp of the underlying 10-minute record, which
marks the end of the interval it covers. 1h and coarser periods are labelled by their start (see
what a timestamp means). Periods without data are omitted rather than
returned with null values.
10min accepts at most 31 days between start and end, and 1h at most 366 days. A longer window is rejected
with 400, so queries at these two periods must set start and end.
start and end are UTC dates, and end is exclusive. Every response returns the window it actually covers as
start and end. When the request omits them, these fields give the period that was totalled.
# one turbine's wind speed, 10 minutes by 10 minutes, for January 2026
curl -H "Authorization: Bearer $TIPSPEED_API_KEY" \
"$BASE/api/beta/projects/acme/northfield/query?metrics=wind_speed&period=10min&by_turbine=true&turbines=T01&start=2026-01-01&end=2026-02-01"
Rate limits¶
The limits are 60 requests per minute and 1000 requests per day, counted per API key. A request over the limit
receives a 429 response and should be retried after a delay.
Errors¶
| Status | Meaning |
|---|---|
400 |
Malformed query: unknown metric key, a bin_by that is not binnable, filter bounds without a filter_by, or an inverted range. The response body identifies the error. |
401 |
No key, an invalid or revoked key, or a key whose user is not in the beta. |
404 |
The project does not exist, or is not accessible to the key's user. |
422 |
A required parameter is missing, for example metrics on /query. |
429 |
Rate limit exceeded. |
An empty rows list means either that no data falls in the range or that the project has no published
dataset. The two cases are currently not distinguished.