Crake SystemsAPI · version 1

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
Keep the key secret, like a password: store it in your system's settings, never in a web page. If it leaks, ask Crake to cancel it and issue a new one — the old one stops working straight away.

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

Endpoints

GET/api/v1/me

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"}]}
GET/api/v1/sites

Every site you can see, with each tank's current state. GET /api/v1/sites/{site_id} returns one site.

Field (per tank)MeaningExample
id, name, zoneThe tank4, "Diesel tank", "North"
pct, litresLevel now (litres only if the capacity is set)59, 1180
statusok, warn, alarm or unknown"ok"
warn_pct, alarm_pctWarning / alarm levels in % full30, 15
last_readingdistance_cm, rssi, snr, at, error
staleNo reading for over 3 hoursfalse
trendstatus: empty / full (with days), steady or not_enough_data{"status":"empty","days":4.2}
recent_dropA sudden drop (possible theft or leak) in the last 24 h, else null{"from_pct":92,"to_pct":60,…}
capacity_l, direction, lat, lngAbout the tank
kindtank or temperature (see above)"tank"
GET/api/v1/sites/{site_id}/tanks/{tank_id}/readings

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}, …]}
GET/api/v1/sites/{site_id}/alarms

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%"}]}
GET/api/v1/caller?number={phone number}

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.