Turq API

What the API can do

• log measurements, including several values from the same moment in one request
• record a dose, for example when your dosing pump has run
• mark the current occurrence of a task as done, for example when your auto feeder has fed
• send a push notification to your own phone
• fetch your tanks, parameters with unit and input limits, dosing products and task templates, optionally with target range, remaining amount and due status
• fetch the latest reading of each parameter
• check with a self-test whether your key works

What it can't do

• It doesn't return history. You can only read the latest value of each parameter, no older readings, photos or journal entries.
• It doesn't control equipment. Turq doesn't switch pumps, heaters or lights. Values you read aren't meant for your device to switch equipment with either, see Not for control.
• It doesn't create anything. You set up tanks, task templates and dosing products in the app.
• It isn't an alarm system. It only sends push notifications when your device triggers them, and whether they arrive also depends on your phone, network and push service. Don't rely on them alone for a critical failure.

You can use the API without a subscription, with a free, secured account. It only writes to tanks you can also edit in the app, and only reads tanks you can see in the app.

The full technical reference is further down and available as openapi.yaml to download.

What you need

• A secured Turq account. Guest accounts can't create keys. Securing your account is free and done in the app.
• A tank you can see in the app. That can be your own or one someone shares with you. To write to it, you need to be able to edit it in the app; if it's read-only, it won't accept anything through the API, but you can still read it.
• For tasks and doses, a task template or dosing product you created in the app beforehand.
• A device or program that can send HTTPS requests with a custom header, such as Home Assistant, an ESPHome device, Node-RED or cURL.
• For measurements, a correctly set clock, because every measurement carries a timestamp.

When new terms are published

When Turq publishes new terms or a new privacy policy, the app asks for your agreement the next time you open it. Your keys, however, keep working for a transition period, so your devices don't stop overnight. This applies if you had agreed to the previous version.

• End of the period: While it runs, API responses carry the X-Turq-Consent-Deadline header. It gives the end of the period as an ISO 8601 timestamp in UTC. The app and the email about the new terms tell you the last day; the timestamp in the header is a little later, so that this day counts in full in every time zone.
• After the period: If you haven't agreed by then, the API answers with 403 and CONSENT_REQUIRED. Your keys and data are kept. As soon as you agree in the app, your keys work again right away.
• No extension: If another new version is published during the period, the period still ends at the stated time.
• No period, no header: If the header is missing, you have agreed or no period is running. It only gives the end of the transition period, not necessarily the end of access: if your account keeps running longer for another reason, for example after you declined new terms, the header doesn't change.
• Tip: Have your device read the header and show you a notice in good time, for example on your dashboard.

Your first entry in three steps

1. Create a key. In the app, open Settings › Integrations › API Keys and tap "Create API key". Give the key a name, such as "Home Assistant", and choose what it may do and which tanks it applies to. Copy the key right away, because Turq shows it only this once.
2. Test the connection. Send POST https://api.turq.app/v1/ping with the header Authorization: Bearer <your key>. If the API answers with "valid": true, the key works. The answer also lists what the key may do and the IDs of its tanks. The test doesn't log anything.

   curl -i -X POST "https://api.turq.app/v1/ping" \
     -H "Authorization: Bearer <YOUR_API_KEY>"

3. Add the command. Right after creating the key, or later via "Set up device" on the key, the app builds the matching command with your IDs filled in, for example for Home Assistant or cURL. Paste it and replace the placeholders. After the first successful entry, Turq sends you a push notification that your device is connected.

Handling your key

A key is like a password for your tanks: whoever has it can log entries there in your name or read along, depending on what the key may do.

• Keep it secret. Turq only stores a hash of the key. After creation nobody can display it again, not even us.
• One key per device. Every push notification then shows which device it came from, and you can disconnect a single device without touching the others. If a device reads and writes, it still gets just one key with both permissions.
• Only the permissions it needs. A temperature probe doesn't need push notifications and usually no read permissions either. You set permissions and tanks when you create the key; for different permissions, create a new key.
• Only in a secret store. In Home Assistant and ESPHome, the key belongs in secrets.yaml; in Node-RED, in the node's credentials. Never in JavaScript that runs in the browser, such as a dashboard card: anyone who opens the dashboard can read it there.
• Never in public repos, forums or screenshots. All keys start with turq_sk_, so you can search for that before you share a configuration.
• You can revoke a key at any time under Settings › Integrations › API Keys › "Revoke key". It takes effect immediately. If a key got into the wrong hands, revoke it and create a new one.

What a key gives away if it gets into the wrong hands

• With read permissions: the names of your tanks, dosing products and task templates, your parameters and, depending on the permissions, target ranges, remaining amounts, due tasks and the latest readings. Always only for the key's tanks.
• With write permissions, someone can log entries in your name and, if the key may do that, send you push notifications. If the key can also read, a stranger finds the IDs needed for writing more easily, and their entries stand out less.
• No key reveals your sign-in details, your email address or tanks that aren't linked to it.

The app shows how many keys you can have active at once.

Reading values and settings

Your device can fetch what it needs to work. There are three read permissions for this. None of them includes another, so you choose exactly what a key may see. When you create a key, you'll find them in the app under "Can read"; nothing is preselected there.

• CONFIG_READ, "Core data" in the app: the key's tanks, the parameters with unit, decimal places, step size and plausible range, the dosing products and the task templates, each with their IDs. This way your device knows the allowed input before it sends a value.
• STATUS_READ, "Current status" in the app: adds the current state to these responses: the target range of each parameter, the remaining amount of each dosing product, and whether a task is due right now and when it's due next. On its own it does nothing, so in the app you choose it together with "Core data".
• MEASUREMENTS_READ, "Latest measurements" in the app: the newest value of each parameter, with its time and origin. The API doesn't return older values.

Read and write permissions can be combined on one key. A device that reads and logs entries needs just one key.

• Older keys can only write. A key's permissions can't be changed, and keys from before version 1.1 don't get read permissions added. To read, create a new key and revoke the old one once your device has moved over.
• Read-only tanks stay readable. Only entries are rejected there, with AQUARIUM_LOCKED. In the list of tanks, readOnly shows which ones they are.
• Shared tanks: you can read them as long as you have access in the app. Members of a tank you share can also create keys for their devices to read it. You see these devices in the app on the tank under "Members’ devices" and can disconnect them there.

Example: a dial next to the tank

A small dial with a display hangs next to the tank, for example one based on an ESP32. You measure KH with a drop test, turn the dial to the value and press. For this it needs a single key with CONFIG_READ, MEASUREMENTS_READ and MEASUREMENTS_WRITE:

1. At startup it calls GET /v1/aquariums/<tank ID>/parameters?parameters=kh and gets the unit, step size, decimal places and plausible range. That way the dial only offers values Turq will accept.
2. Then it fetches the latest value with GET …/measurements/latest?parameters=kh and shows it together with its age.
3. After measuring it sends the dialed value with POST …/measurements and an Idempotency-Key. That way a repeat after a dropped connection still creates only one entry.

If the key also has TASKS_WRITE, the same dial marks the task "Measure KH" as done right away. With STATUS_READ it shows beforehand whether that task is due.

How often your device should ask

• Structure (tanks, parameters, dosing products, task templates): at startup and then about once an hour. It rarely changes.
• Latest value: at most every 5 minutes. Asking more often doesn't make it fresher, because it only changes when someone measures and logs a value.
• Conditional requests save data: send the ETag of the last response as If-None-Match. If nothing has changed, you get 304 without a body. For the limits, though, a 304 counts like any other request: it saves data, not requests.
• On 429, wait the seconds given in Retry-After, then continue at your usual pace.

Headers for reading

• ETag (response): identifies the content of the response. Keep it together with the response and send it back unchanged, including a leading W/.
• If-None-Match (request): the ETag you kept. If the API answers with 304, the response you kept is still valid.
• Cache-Control: private, no-store (response): proxies and browsers don't store read responses. Your device may keep them itself.
• Date (response): the server time. Work out the age of a value from timestamp and this header, not from your device's clock.
• X-Turq-Consent-Deadline (response): only set during a transition period after new terms.

When reading doesn't work

• SCOPE_DENIED with an older key: it can only write. Create a new key with read permissions.
• SCOPE_DENIED despite a read permission: each route needs its own permission. …/measurements/latest needs MEASUREMENTS_READ, the other read routes need CONFIG_READ.
• SERVICE_DISABLED only when reading: we've paused reading for now, but the API still accepts entries. Show the last state you read together with its age and ask again later.
• CONSENT_REQUIRED: the transition period after new terms has ended. As soon as you agree in the app, the API answers again right away.
• AQUARIUM_NOT_ALLOWED: the tank no longer exists, you no longer have access to it, or it isn't linked to the key. GET /v1/aquariums and the self-test list the tanks your key can use right now.
• 304 without a body: not an error. Nothing has changed since your last request. If your device didn't keep anything, for example after a restart, ask without If-None-Match.
• A parameter is missing from the response: there's no value yet, the parameter isn't active in Turq, or its parameter key is misspelled. The API skips unknown parameter keys instead of reporting an error.
• value is null or operator is set: the value was logged as a limit, such as "less than" or "below the detection limit" (belowDetection). Show that too, not just a number.
• VALIDATION_FAILED with ?parameters=: send the parameter keys as one comma-separated list, such as parameters=kh,ca, not as parameters[]=.

Not for controlling devices

Values you read are meant for display: on a screen next to the tank, on your dashboard, in a reminder. Turq doesn't support using them to control equipment, such as switching a dosing pump, a heater or an auto top-off based on a Turq value. That's why you won't find recipes for that here.

The reason: a value in Turq is a logbook entry, not a real-time measurement.

• It can be wrong. A typo, an old reagent or a drifting sensor ends up in the logbook like any other value.
• It can be backdated. timestamp is the time given by whoever logged the value, not when it reached Turq.
• It can come from someone else. Members of a shared tank and their devices log entries to the same logbook.
• It can be missing. The API may be paused, a limit may be reached, or the connection may be down. We don't commit to any availability.

To help you judge a value, it carries origin (how it got into the logbook, for example via the app, a lab import or the API), viaApi (whether a device logged it with a key) and timestamp. Always show a value's age along with it.

Display names as text only

The names of tanks, dosing products and task templates were typed by people, in shared tanks also by members. Turq removes control characters and shortens long names, but doesn't check what they say.

• Only display them as text. Never insert them unchecked into HTML, code, templates or commands.
• Don't pass them to voice assistants or chatbots that may switch devices. A name can be phrased like an instruction.
• Work with IDs, not names. Names can change at any time and don't have to be unique.

Recipes

Here you can see what the request looks like for common systems. For Home Assistant and cURL, the app builds the command with your IDs; the examples here show what's inside. We name these systems only to help you find the right recipe. Turq is not affiliated with any of these projects.

Jump to: Home Assistant · ESPHome · Node-RED · cURL

turq_bearer: "Bearer <YOUR_API_KEY>"

rest_command:
  turq_measurement:
    url: "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/measurements"
    method: POST
    content_type: application/json
    headers:
      Authorization: !secret turq_bearer
    payload: '{"timestamp": {{ (now().timestamp() * 1000) | int }}, "values": {"ph": {{ states("sensor.my_sensor") | float }} } }'
  turq_dosing:
    url: "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/dosing-events"
    method: POST
    content_type: application/json
    headers:
      Authorization: !secret turq_bearer
    payload: '{"productId": "9b2e5d7c-0a1f-4c3b-8d6e-1f2a3b4c5d6e", "amount": 2.5, "type": "manual_dose", "unit": "ml"}'
  turq_task:
    url: "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/tasks/complete"
    method: POST
    content_type: application/json
    headers:
      Authorization: !secret turq_bearer
    payload: '{"templateId": "7c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"}'
  turq_notify:
    url: "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/notifications"
    method: POST
    content_type: application/json
    headers:
      Authorization: !secret turq_bearer
    payload: '{"title": "Tank", "body": "Water level is low"}'

automation:
  - alias: Send Turq measurement
    triggers:
      - trigger: time_pattern
        minutes: "/15"
    actions:
      - action: rest_command.turq_measurement

turq_measurements_url: "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/measurements"
turq_bearer: "Bearer <YOUR_API_KEY>"

time:
  - platform: sntp
    id: sntp_time

http_request:
  timeout: 10s

interval:
  - interval: 15min
    then:
      - http_request.post:
          url: !secret turq_measurements_url
          headers:
            Content-Type: application/json
            Authorization: !secret turq_bearer
          json: |-
            root["timestamp"] = (int64_t) id(sntp_time).now().timestamp * 1000;
            root["values"]["ph"] = id(my_sensor).state;

msg.payload = {
  "timestamp": Date.now(),
  "values": {
    "ph": <number>
  }
};
return msg;

msg.payload = {
  "productId": "9b2e5d7c-0a1f-4c3b-8d6e-1f2a3b4c5d6e",
  "amount": 2.5,
  "type": "manual_dose",
  "unit": "ml"
};
return msg;

msg.payload = {
  "templateId": "7c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"
};
return msg;

msg.payload = {
  "title": "Tank",
  "body": "Water level is low"
};
return msg;

read -rs TURQ_API_KEY && export TURQ_API_KEY

curl -i -X POST "https://api.turq.app/v1/ping" \
  -H "Authorization: Bearer $TURQ_API_KEY"

TURQ_API_KEY=<YOUR_API_KEY>
*/15 * * * * curl -s -X POST "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/measurements" -H "Authorization: Bearer $TURQ_API_KEY" -H "Content-Type: application/json" -d '{"timestamp": '"$(date +\%s)000"', "values": {"ph": <number>}}'

curl -i -X POST "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/dosing-events" \
  -H "Authorization: Bearer $TURQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productId": "9b2e5d7c-0a1f-4c3b-8d6e-1f2a3b4c5d6e", "amount": 2.5, "type": "manual_dose", "unit": "ml"}'

curl -i -X POST "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/tasks/complete" \
  -H "Authorization: Bearer $TURQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "7c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"}'

curl -i -X POST "https://api.turq.app/v1/aquariums/3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01/notifications" \
  -H "Authorization: Bearer $TURQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Tank", "body": "Water level is low"}'

Limits

To keep the API reliable for everyone, Turq limits how often data is read and how often and how much is written. The limits are the same for everyone, with or without Pro. We deliberately don't list fixed numbers here, because we adjust them as we go. Your device learns everything it needs from the responses.

• Too many requests at once: the API answers with 429 and RATE_LIMITED. The Retry-After header gives the seconds to wait.
• Daily limit per tank: measurements and doses also have a limit per tank and day. Successful responses carry the headers X-Turq-Daily-Limit (the limit) and X-Turq-Daily-Remaining (what's left today). For measurements, every single value counts, not every request. The day starts at 00:00 UTC.
• Limit reached: you get 429 with DAILY_LIMIT_REACHED, and Retry-After counts down to midnight UTC. The app also shows a notice in your notifications.
• Rejected requests and repeats with the same Idempotency-Key don't count.
• Reading has its own limits, separate from writing. There too, too many requests return 429 with RATE_LIMITED and Retry-After. Reading has no daily limit per tank, and a 304 counts like any other request.

How to stay comfortably below them

• Send measurements on a fixed schedule instead of on every small change. The commands from the app send every 15 minutes; water parameters change slowly.
• Bundle the values from one moment into one request, such as temperature and pH together.
• Don't retry failed requests in a tight loop. Follow Retry-After, and for errors without that header, wait a little longer each time.
• Send push notifications only for events, not on a schedule.
• Only fetch values as often as your device needs them. You'll find the right pace under Reading.

Avoiding duplicate entries

Give write requests an Idempotency-Key header with a unique value per event, such as a UUID, and reuse that value when you repeat the same request: Turq then logs the event only once and answers the repeat with "replayed": true. If the first request is still running, you get 409 with IDEMPOTENCY_IN_PROGRESS and Retry-After, and the same value with different content returns 409 with IDEMPOTENCY_KEY_REUSED.

Errors

Every error has the same format: {"error": {"code": …, "message": …, "requestId": …}}. Have your code check code, not the text in message, which may change. We need the requestId if you contact us.

Reference

All routes, fields and responses in detail. The base URL is https://api.turq.app/v1; every request needs the Authorization: Bearer <key> header, and write requests send JSON. The reference is generated from the same file you can download here. We check it against the code automatically with every change.

Download openapi.yaml

OpenAPI 3.1. Import the file into your API tool or generate a client from it.

{
  "valid": true,
  "scopes": [
    "MEASUREMENTS_WRITE",
    "DOSING_WRITE"
  ],
  "aquariumIds": [
    "3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01"
  ]
}

{
  "timestamp": 1761800000000,
  "values": {
    "ph": 7.2
  }
}

{
  "timestamp": 1761800000000,
  "values": {
    "temperature": 25.4,
    "ph": 7.1,
    "no3": 12.5
  }
}

{
  "id": "0b7e2c5a-6f1d-4b8e-9a3c-2d4f6a8c0e12"
}

{
  "productId": "9b2e5d7c-0a1f-4c3b-8d6e-1f2a3b4c5d6e",
  "amount": 2.5,
  "type": "manual_dose",
  "unit": "ml"
}

{
  "id": "5d3c1a9e-8b7f-4e6d-a2c4-0f1e2d3c4b5a"
}

{
  "templateId": "7c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f"
}

{
  "templateId": "7c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "note": "Water change done by the automation"
}

{
  "id": "c4a1e8b2-3d5f-4a7c-9e0b-6f8d1a2b3c4d"
}

{
  "title": "Tank",
  "body": "Water level is low"
}

{
  "sent": true
}

{
  "items": [
    {
      "id": "3f9a6b52-1c1e-4d57-8a3a-6f2d3a8b9c01",
      "name": "Living room reef",
      "readOnly": false
    }
  ]
}

{
  "items": [
    {
      "key": "ph",
      "unit": null,
      "decimals": 1,
      "step": 0.1,
      "plausibleMin": null,
      "plausibleMax": null,
      "target": {
        "min": 8,
        "max": 8.4
      }
    }
  ]
}

{
  "items": [
    {
      "id": "9b2e5d7c-0a1f-4c3b-8d6e-1f2a3b4c5d6e",
      "name": "Alkalinity",
      "unit": "ml",
      "remainingVolume": 412.5
    }
  ]
}

{
  "items": [
    {
      "id": "7c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "name": "Water change",
      "dueNow": true,
      "nextDueAt": 1761800000000
    }
  ]
}

{
  "values": {
    "ph": {
      "value": 8.2,
      "operator": null,
      "belowDetection": false,
      "unit": null,
      "timestamp": 1761800000000,
      "origin": "app",
      "viaApi": false
    },
    "po4": {
      "value": null,
      "operator": "<",
      "belowDetection": true,
      "unit": "mg/l",
      "timestamp": 1761700000000,
      "origin": "lab",
      "viaApi": false
    }
  }
}

Changelog

This is where we note what changes in the API, newest first. The major version is part of the path (/v1). New fields, values and routes are added within /v1, so your code should ignore fields and values it doesn't know. We try to avoid changes that would require you to adjust running devices and list them here once they're settled. Turq is a small project: we don't commit to any availability or minimum support period for a version, and we may pause the API temporarily.

Help and feedback

Send questions, bugs or ideas about the API straight from the app: Settings › Help & Feedback. That's also where you'll find our reply. For errors, include the code, the requestId and what your device sent. We never need your key, so please don't include it. And if you're missing a route, tell us what you'd use it for.

The Turq Terms and our Privacy Policy apply to the API. Details about the provider are in the Imprint.