API reference
Everything the pages do can be done from a program. Version 2, at https://api.tidewater.example/v2
In these docs
On this page
Keys
Make a key under Account → Keys. A key may read, or read and write; give a program only what it needs.
Send it in the Authorization header of every call:
curl -H "Authorization: Bearer tw_live_4f9c…" https://api.tidewater.example/v2/stationsA key is a password. Keep it out of code you share; if one leaks, delete it under Account → Keys and it stops working at once.
Stations
GET /stations lists the stations the key may see. GET /stations/{id} gives one.
The answer
[ { "id": "bergen-harbour", "name": "Bergen harbour", "place": { "lat": 60.3975, "lng": 5.3221 }, "measures": ["level", "temp", "salt"], "lastHeard": "2026-05-14T08:10:00Z" }]Sending
POST /in/{station} takes numbers as form fields or as JSON. A time is optional: without one, it is the moment the call arrives.
curl -X POST https://tidewater.example/in/bergen-harbour \ -H "Content-Type: application/json" \ -d @reading.jsonreading.json
{ "time": "2026-05-14T08:20:00Z", "level": 1.47, "temp": 8.3 }The /in addresses need no key: the station’s address is its own secret. Make a new one under the station’s settings if it is shared by mistake.
Readings
GET /stations/{id}/readings gives what was measured, oldest first.
| from | The first time, ISO 8601 | A day ago |
| to | The last time | Now |
| every | One value per 10m, 1h or 1d (the mean) | Every reading |
| measure | One or more, with commas | All of them |
In JavaScript
const answer = await fetch('https://api.tidewater.example/v2/stations/bergen-harbour/readings?every=1h', { headers: { Authorization: 'Bearer ' + process.env.TIDEWATER_KEY },})const readings = await answer.json()In Python
import os, requestsanswer = requests.get( 'https://api.tidewater.example/v2/stations/bergen-harbour/readings', params={'every': '1h'}, headers={'Authorization': 'Bearer ' + os.environ['TIDEWATER_KEY']},)readings = answer.json()Errors and limits
Every error answers with a code and a sentence that says what to do about it.
| 400 | Something in the call is not as expected | Read the sentence in the answer |
| 401 | No key, or one that was deleted | Send a key that works |
| 403 | The key may not do this | Give it write access, or use another |
| 404 | No such station | Check the id, letter by letter |
| 429 | Too many calls | Wait the seconds in Retry-After |
A key may make 1,000 calls an hour. Sending to /in is not counted: a station may send once a second.