Crake read API
Connect your own systems (fuel ordering, waste collection planning, reporting) to the tank levels Crake measures.
The API is read only and returns JSON. Everything is under /api/v1/; if we ever need to change
something in a way that would break your code, it will go under /api/v2/ and v1 will keep working.
Getting access
Ask Crake for an API key (support@crakesystems.co.uk). A key looks like
cak_…, belongs to your company and sees your company's sites (and any regions or contracts under it) — nothing else.
Send it with every request:
Authorization: Bearer cak_your_key_here
Limits: about 120 requests a minute per address (you'll get 429 with Retry-After if you go over).
Sensors report once an hour, so polling more than every few minutes gains nothing.
Things to know about the data
- Times are UTC, ISO 8601 (
2026-10-19T08:00:31Z). - reading_time is when the sensor measured. A gateway that was offline sends its readings later, so readings can
arrive hours after their
reading_time. Always sort and chart byreading_time. - distance_cm is from the sensor down to the liquid, so a bigger number means emptier. Use
level_pct(andlitreswhere the tank's capacity is known) for levels. - A failed measurement has
distance_cm: nulland astatussuch asno_echo; an impossible distance hasstatus: "out_of_range"and no level. Single readings can be noisy — Crake's own alarms need two readings in a row. - Temperature sensors (rail or cabin) are listed with the tanks, with
kind: "temperature"(tanks havekind: "tank"). They havetemp_c(°C now),min_24h,max_24h, the alarm levelstemp_low_alarm,temp_low_warn,temp_high_warn,temp_high_alarm(null= not used) andside("high"/"low"while too hot / too cold);pctandlitresarenull. Their readings havetemp_c, and their alarms havetype: "temp". - Tank
direction:drainempties (water, fuel — alarm when low);fillfills up (waste — alarm when high).
Endpoints
Who the key belongs to and which sites it can see.
{"api_key": {"label": "Fuel ordering system", "org": "Acme Rail › North"},
"sites": [{"site_id": "ACM-001", "name": "York depot"}]}
Every site you can see, with each tank's current state. GET /api/v1/sites/{site_id} returns one site.
| Field (per tank) | Meaning | Example |
|---|---|---|
id, name, zone | The tank | 4, "Diesel tank", "North" |
pct, litres | Level now (litres only if the capacity is set) | 59, 1180 |
status | ok, warn, alarm or unknown | "ok" |
warn_pct, alarm_pct | Warning / alarm levels in % full | 30, 15 |
last_reading | distance_cm, rssi, snr, at, error | |
stale | No reading for over 3 hours | false |
trend | status: empty / full (with days), steady or not_enough_data | {"status":"empty","days":4.2} |
recent_drop | A sudden drop (possible theft or leak) in the last 24 h, else null | {"from_pct":92,"to_pct":60,…} |
capacity_l, direction, lat, lng | About the tank | |
kind | tank or temperature (see above) | "tank" |
Every reading of one tank, oldest first. Query: from, to (a date like 2026-10-01
or a time; default the last 7 days; at most 400 days), limit (default 5000, max 10000 — if
truncated is true, ask again from the last reading_time).
{"site_id": "ACM-001", "tank_id": 4, "from": "2026-10-12T00:00:00Z", "to": "2026-10-19T09:00:00Z",
"count": 168, "truncated": false,
"readings": [{"reading_time": "2026-10-12T00:00:31Z", "distance_cm": 109, "level_pct": 91,
"litres": 1820, "temp_c": null, "status": "ok", "rssi": -61, "snr": 7}, …]}
Alarm history, newest first. Query: from, to (default the last 30 days).
type is level, no_data, drop (sudden drop) or temp (temperature);
ended_at is null while an alarm is still on.
{"alarms": [{"id": 12, "tank_id": 4, "tank": "Diesel tank", "type": "level", "severity": "warn",
"started_at": "2026-10-18T06:00:40Z", "ended_at": "2026-10-18T14:00:38Z", "detail": "28%"}]}
Who is ringing: for a caller pop-up in your phone system (for example a 3CX CRM integration). Finds the
customer(s) with that phone number on your sites, however the number is written (07700 900123,
+44 7700 900123). The first match's fields are at the top level, all of them in matches;
found is false when nobody matches. If your phone system can't send the
Authorization header, add &key=cak_… to the address instead (this endpoint only).
{"found": true, "name": "Mrs Jones", "first_name": "Mrs", "last_name": "Jones",
"phone": "07700 900123", "email": "jones@example.com", "house": "1 High Street", "village": "Doddington",
"level_pct": 39, "estimated": true, "due": "due Fri 13 Nov", "reorder_date": "2026-11-13",
"last_delivery": {"date": "2026-04-08", "litres": 780, "by": null},
"summary": "Mrs Jones · Doddington · ~39% (estimate) · due Fri 13 Nov · last delivery Wed 8 Apr (780 L)",
"url": "https://app.crakesystems.co.uk/dashboard.html?site=…&tank=…", "matches": [ … ]}
Errors
401 missing or cancelled key · 404 a site or tank your key can't see (or doesn't exist) ·
400 a bad from / to (or no number) · 429 too many requests. The body is
{"error": "plain English"}.
Examples
curl
curl -H "Authorization: Bearer cak_your_key_here" \
"https://app.crakesystems.co.uk/api/v1/sites"
PowerShell
$h = @{ Authorization = "Bearer cak_your_key_here" }
(Invoke-RestMethod -Uri "https://app.crakesystems.co.uk/api/v1/sites" -Headers $h).sites |
ForEach-Object { $_.tanks } | Select-Object name, pct, litres, status
Python
import requests
r = requests.get("https://app.crakesystems.co.uk/api/v1/sites/ACM-001/tanks/4/readings",
params={"from": "2026-10-01"},
headers={"Authorization": "Bearer cak_your_key_here"}, timeout=30)
for x in r.json()["readings"]:
print(x["reading_time"], x["level_pct"])
Crake Systems · remote tank monitoring ·
questions: support@crakesystems.co.uk · 07918 104186
Crake Systems Limited, registered in England and Wales, company number 17544712. Registered office: First Floor, Chequers, 28 Whitehorse Street, Baldock, Hertfordshire, SG7 6QQ. Registered with the ICO, number ZC289708.