The HTTP API

Every refinery instance serves its complete API over HTTP, under the /api prefix. This is the very protocol the Python client speaks: pointing timeseries() at an http uri yields the same api points with the same semantics as a direct postgres uri (see API documentation) — and it is also how federated instances consume each other (see Securing the Refinery).

Interactive reference

The authoritative, always up-to-date endpoint reference is served by the instance itself: browse https://<your-instance>/api for the interactive (swagger) console, listing every endpoint with its parameters, responses, and a try-it-out mode.

Speaking to it directly

Requests authenticate with a bearer token (see Securing the Refinery). Most endpoints speak plain json:

$ curl -H "Authorization: Bearer $TOKEN" \
    'https://refinery.example.com/api/series/metadata?name=banana-spot-price'
{"unit": "eur", "source": "market"}

The series values endpoints (/series/state, /series/history and friends) return a compact binary encoding rather than json: they are designed for the Python and Excel clients. For scripted access to the values, prefer the Python client over an http uri:

from tshistory.api import timeseries
tsa = timeseries('https://refinery.example.com/api')
ts = tsa.get('banana-spot-price')