Turq-API

Was die API kann

• Messwerte eintragen, auch mehrere Werte eines Zeitpunkts in einer Anfrage
• eine Dosierung festhalten, etwa wenn deine Dosierpumpe gelaufen ist
• den aktuell fälligen Termin einer Aufgabe abhaken, zum Beispiel wenn dein Futterautomat gefüttert hat
• dir eine Push-Nachricht aufs eigene Handy schicken
• deine Becken, Parameter mit Einheit und Eingabegrenzen, Dosierprodukte und Aufgaben-Vorlagen abfragen, auf Wunsch mit Zielbereich, Restmenge und Fälligkeit
• den letzten Messwert je Parameter abfragen
• mit einem Selbsttest prüfen, ob dein Key funktioniert

Was sie nicht kann

• Sie liefert keinen Verlauf. Lesen kannst du nur den letzten Wert je Parameter, keine älteren Messwerte, keine Fotos und kein Journal.
• Sie steuert keine Technik. Turq schaltet keine Pumpe, keinen Heizer und kein Licht. Gelesene Werte sind auch nicht dafür gedacht, dass dein Gerät damit Technik schaltet, siehe Nicht zum Steuern.
• Sie legt nichts an. Becken, Aufgaben-Vorlagen und Dosierprodukte richtest du in der App ein.
• Sie ist kein Alarmsystem. Push-Nachrichten verschickt sie nur, wenn dein Gerät sie auslöst, und ob sie ankommen, hängt auch von Handy, Netz und Push-Dienst ab. Verlass dich bei einer kritischen Störung nicht allein darauf.

Die API ist ohne Abo nutzbar, mit einem kostenlosen, gesicherten Konto. Sie schreibt nur in Becken, die du auch in der App bearbeiten darfst, und liest nur Becken, die du in der App siehst.

Die vollständige technische Referenz findest du weiter unten und als openapi.yaml zum Herunterladen. Sie ist auf Englisch.

Was du brauchst

• Ein gesichertes Turq-Konto. Gastkonten können keine Keys anlegen. Das Sichern ist kostenlos und geht in der App.
• Ein Becken, das du in der App siehst. Das kann dein eigenes sein oder eines, das jemand mit dir teilt. Zum Eintragen musst du es in der App bearbeiten dürfen; ist es schreibgeschützt, nimmt es über die API nichts an, lesen kannst du es aber weiter.
• Für Aufgaben und Dosierungen eine Aufgaben-Vorlage oder ein Dosierprodukt, das du vorher in der App angelegt hast.
• Ein Gerät oder Programm, das HTTPS-Anfragen mit eigenem Header senden kann, zum Beispiel Home Assistant, ein ESPHome-Gerät, Node-RED oder cURL.
• Für Messwerte eine richtig gestellte Uhr, denn jeder Messwert trägt einen Zeitstempel.

Wenn neue Bedingungen erscheinen

Veröffentlicht Turq neue Nutzungsbedingungen oder eine neue Datenschutzerklärung, bittet dich die App beim nächsten Öffnen um deine Zustimmung. Deine Keys laufen dagegen eine Übergangsfrist weiter, damit deine Geräte nicht von einem Tag auf den anderen stehen bleiben. Das gilt, wenn du der vorigen Fassung zugestimmt hattest.

• Ende der Frist: Solange sie läuft, tragen die Antworten der API den Header X-Turq-Consent-Deadline. Er nennt das Ende der Frist als ISO-8601-Zeitpunkt in UTC. Die App und die Mail zu den neuen Bedingungen nennen dir den letzten Tag; der Zeitpunkt im Header liegt etwas danach, damit dieser Tag in jeder Zeitzone ganz zählt.
• Nach der Frist: Hast du bis dahin nicht zugestimmt, antwortet die API mit 403 und CONSENT_REQUIRED. Keys und Daten bleiben erhalten. Sobald du in der App zustimmst, laufen deine Keys sofort wieder.
• Keine Verlängerung: Erscheint während der Frist noch eine neue Fassung, endet die Frist trotzdem zum genannten Zeitpunkt.
• Ohne Frist kein Header: Fehlt der Header, hast du zugestimmt, oder es läuft keine Frist. Er nennt nur das Ende der Übergangsfrist, nicht unbedingt das Ende des Zugriffs: Läuft dein Konto aus einem anderen Grund länger weiter, etwa nach einer Ablehnung neuer Bedingungen, ändert sich der Header nicht.
• Tipp: Lass dein Gerät den Header auswerten und dir rechtzeitig einen Hinweis zeigen, etwa im Dashboard.

In drei Schritten zum ersten Eintrag

1. Key anlegen. Öffne in der App Einstellungen › Integrationen › API-Keys und tipp auf „API-Key erstellen“. Gib dem Key einen Namen, etwa „Home Assistant“, und wähl, was er darf und für welche Becken er gilt. Kopier den Key sofort, denn Turq zeigt ihn nur dieses eine Mal.
2. Verbindung testen. Schick POST https://api.turq.app/v1/ping mit dem Header Authorization: Bearer <dein Key>. Antwortet die API mit "valid": true, passt der Key. Die Antwort nennt auch, was der Key darf, und die IDs seiner Becken. Der Test trägt nichts ein.

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

3. Befehl einbauen. Direkt nach dem Anlegen, oder später über „Gerät einrichten“ am Key, baut dir die App den passenden Befehl mit deinen IDs, etwa für Home Assistant oder cURL. Füg ihn ein und ersetz die Platzhalter. Nach dem ersten erfolgreichen Eintrag schickt dir Turq eine Push-Nachricht, dass dein Gerät verbunden ist.

Mit deinem Key umgehen

Ein Key ist wie ein Passwort für deine Becken: Wer ihn hat, kann dort in deinem Namen eintragen oder mitlesen, je nachdem, was der Key darf.

• Halte ihn geheim. Turq speichert nur einen Hash des Keys. Nach dem Anlegen kann ihn niemand mehr anzeigen, auch wir nicht.
• Ein Key pro Gerät. Dann siehst du in jeder Push-Nachricht, von welchem Gerät sie kommt, und kannst ein einzelnes Gerät trennen, ohne die anderen anzufassen. Liest und schreibt ein Gerät, bekommt es trotzdem nur einen Key mit beiden Rechten.
• Nur die nötigen Rechte. Ein Temperaturfühler braucht keine Push-Nachrichten und meist auch keine Leserechte. Rechte und Becken legst du beim Anlegen fest; für andere Rechte legst du einen neuen Key an.
• Nur in einen Secret-Speicher. In Home Assistant und ESPHome gehört der Key in die secrets.yaml, in Node-RED zu den Zugangsdaten der Node. Nie in JavaScript, das im Browser läuft, etwa in einer Dashboard-Karte: Dort kann ihn jeder auslesen, der das Dashboard öffnet.
• Nie in öffentliche Repos, Foren oder Screenshots. Alle Keys beginnen mit turq_sk_. Danach kannst du suchen, bevor du eine Konfiguration teilst.
• Widerrufen geht jederzeit unter Einstellungen › Integrationen › API-Keys › „Key widerrufen“. Das wirkt sofort. Ist ein Key in falsche Hände geraten, widerruf ihn und leg einen neuen an.

Was ein Key verrät, wenn er in falsche Hände gerät

• Mit Leserechten: die Namen deiner Becken, Dosierprodukte und Aufgaben-Vorlagen, deine Parameter und je nach Rechten auch Zielbereiche, Restmengen, fällige Aufgaben und die letzten Messwerte. Immer nur für die Becken des Keys.
• Mit Schreibrechten kann jemand in deinem Namen eintragen und dir, wenn der Key das darf, Push-Nachrichten schicken. Darf der Key auch lesen, findet ein Fremder damit leichter die IDs, die er zum Schreiben braucht, und seine Einträge fallen weniger auf.
• Kein Key verrät deine Anmeldedaten, deine E-Mail-Adresse oder Becken, die nicht zu ihm gehören.

Wie viele Keys du gleichzeitig aktiv haben kannst, zeigt dir die App.

Werte und Einstellungen lesen

Dein Gerät kann abfragen, was es zum Arbeiten braucht. Dafür gibt es drei Leserechte. Keins schließt ein anderes ein, du wählst also genau, was ein Key sehen darf. Beim Anlegen findest du sie in der App unter „Darf lesen“; vorausgewählt ist dort nichts.

• CONFIG_READ, in der App „Grunddaten“: die Becken des Keys, die Parameter mit Einheit, Nachkommastellen, Schrittweite und plausiblem Bereich, die Dosierprodukte und die Aufgaben-Vorlagen, jeweils mit ihren IDs. So kennt dein Gerät die erlaubten Eingaben, bevor es einen Wert schickt.
• STATUS_READ, in der App „Aktueller Stand“: ergänzt diese Antworten um den Zustand: den Zielbereich je Parameter, die Restmenge je Dosierprodukt und ob eine Aufgabe gerade fällig ist und wann sie als Nächstes fällig wird. Allein bringt es nichts, deshalb wählst du es in der App zusammen mit „Grunddaten“.
• MEASUREMENTS_READ, in der App „Letzte Messwerte“: den neuesten Wert je Parameter, mit Zeitpunkt und Herkunft. Ältere Werte liefert die API nicht.

Lese- und Schreibrechte lassen sich auf einem Key kombinieren. Ein Gerät, das liest und einträgt, braucht also nur einen Key.

• Ältere Keys können nur schreiben. Die Rechte eines Keys lassen sich nicht ändern, auch Keys aus der Zeit vor Version 1.1 bekommen kein Leserecht dazu. Leg zum Lesen einen neuen Key an und widerruf den alten, sobald dein Gerät umgezogen ist.
• Schreibgeschützte Becken bleiben lesbar. Nur Einträge lehnt die API dort mit AQUARIUM_LOCKED ab. In der Liste der Becken zeigt readOnly, welche das sind.
• Geteilte Becken: Du liest sie, solange du in der App Zugriff hast. Mitglieder eines Beckens, das du teilst, können für ihre Geräte ebenfalls Keys zum Lesen anlegen. Du siehst diese Geräte in der App beim Becken unter „Geräte der Mitglieder“ und kannst sie dort trennen.

Beispiel: ein Drehregler am Becken

Neben dem Becken hängt ein kleiner Drehregler mit Display, etwa auf Basis eines ESP32. Du misst KH mit dem Tropftest, drehst den Wert ein und drückst. Dafür braucht er einen einzigen Key mit CONFIG_READ, MEASUREMENTS_READ und MEASUREMENTS_WRITE:

1. Beim Start fragt er GET /v1/aquariums/<Becken-ID>/parameters?parameters=kh ab und bekommt Einheit, Schrittweite, Nachkommastellen und den plausiblen Bereich. So bietet der Regler nur Werte an, die Turq auch annimmt.
2. Dann holt er mit GET …/measurements/latest?parameters=kh den letzten Wert und zeigt ihn mit seinem Alter an.
3. Nach dem Messen schickt er den eingedrehten Wert mit POST …/measurements und einem Idempotency-Key. So entsteht auch bei einer Wiederholung nach einem Verbindungsabbruch nur ein Eintrag.

Bekommt der Key noch TASKS_WRITE, hakt derselbe Regler die Aufgabe „KH messen“ gleich mit ab. Mit STATUS_READ zeigt er vorher an, ob sie fällig ist.

Wie oft dein Gerät abfragen sollte

• Struktur (Becken, Parameter, Dosierprodukte, Aufgaben-Vorlagen): beim Start und danach etwa stündlich. Sie ändert sich selten.
• Letzter Wert: höchstens alle 5 Minuten. Öfter fragen macht ihn nicht frischer, denn er ändert sich erst, wenn jemand misst und einträgt.
• Bedingt abfragen spart Datenvolumen: Schick den ETag der letzten Antwort als If-None-Match mit. Hat sich nichts geändert, kommt 304 ohne Inhalt. Bei den Grenzen zählt ein 304 aber wie jede andere Abfrage: Er spart Daten, keine Abfragen.
• Bei 429 wartest du die Sekunden aus Retry-After ab und machst dann im gewohnten Takt weiter.

Header beim Lesen

• ETag (Antwort): kennzeichnet den Inhalt der Antwort. Heb ihn zusammen mit der Antwort auf und schick ihn unverändert zurück, auch mit einem W/ am Anfang.
• If-None-Match (Anfrage): der aufgehobene ETag. Antwortet die API mit 304, gilt deine aufgehobene Antwort weiter.
• Cache-Control: private, no-store (Antwort): Proxys und Browser speichern Leseantworten nicht. Dein Gerät darf sie selbst aufheben.
• Date (Antwort): die Serverzeit. Rechne das Alter eines Werts aus timestamp und diesem Header aus, nicht mit der Uhr deines Geräts.
• X-Turq-Consent-Deadline (Antwort): nur während einer Übergangsfrist nach neuen Bedingungen gesetzt.

Wenn das Lesen nicht klappt

• SCOPE_DENIED bei einem älteren Key: Er kann nur schreiben. Leg einen neuen Key mit Leserechten an.
• SCOPE_DENIED trotz Leserecht: Jede Route braucht ihr eigenes Recht. …/measurements/latest braucht MEASUREMENTS_READ, die anderen Leserouten brauchen CONFIG_READ.
• SERVICE_DISABLED nur beim Lesen: Wir haben das Lesen vorübergehend pausiert, Einträge nimmt die API weiter an. Zeig den zuletzt gelesenen Stand mit seinem Alter an und frag später wieder.
• CONSENT_REQUIRED: Die Übergangsfrist nach neuen Bedingungen ist vorbei. Sobald du in der App zustimmst, antwortet die API sofort wieder.
• AQUARIUM_NOT_ALLOWED: Das Becken gibt es nicht mehr, du hast keinen Zugriff mehr darauf, oder es gehört nicht zum Key. GET /v1/aquariums und der Selbsttest nennen die Becken, die dein Key gerade nutzen kann.
• 304 ohne Inhalt: kein Fehler. Seit deiner letzten Abfrage hat sich nichts geändert. Hat dein Gerät nichts aufgehoben, etwa nach einem Neustart, frag ohne If-None-Match.
• Ein Parameter fehlt in der Antwort: Es gibt noch keinen Wert, der Parameter ist in Turq nicht aktiv, oder sein Schlüssel ist falsch geschrieben. Unbekannte Schlüssel überspringt die API, statt einen Fehler zu melden.
• value ist null oder operator ist gesetzt: Der Wert wurde als Grenzangabe eingetragen, etwa „kleiner als“ oder „unter der Nachweisgrenze“ (belowDetection). Zeig das mit an, statt nur eine Zahl.
• VALIDATION_FAILED bei ?parameters=: Schick die Schlüssel als eine kommagetrennte Liste, etwa parameters=kh,ca, nicht als parameters[]=.

Nicht zum Steuern von Geräten

Gelesene Werte sind zum Anzeigen da: auf einem Display am Becken, in deinem Dashboard, in einer Erinnerung. Turq unterstützt es nicht, damit Technik zu steuern, also etwa eine Dosierpumpe, einen Heizer oder einen Nachfüller nach einem Turq-Wert zu schalten. Rezepte dafür gibt es hier deshalb nicht.

Der Grund: Ein Wert in Turq ist ein Eintrag im Logbuch, keine Messung in Echtzeit.

• Er kann falsch sein. Ein Tippfehler, ein altes Reagenz oder ein driftender Sensor landet im Logbuch wie jeder andere Wert.
• Er kann rückdatiert sein. timestamp ist der Zeitpunkt, den der Eintragende angegeben hat, nicht der Eingang bei Turq.
• Er kann von jemand anderem stammen. Mitglieder eines geteilten Beckens und ihre Geräte tragen ins selbe Logbuch ein.
• Er kann fehlen. Die API kann pausiert sein, eine Grenze kann erreicht sein, oder die Verbindung fehlt. Wir sichern keine Verfügbarkeit zu.

Damit du einen Wert einordnen kannst, trägt er origin (auf welchem Weg er ins Logbuch kam, etwa per App, Laborimport oder API), viaApi (ob ein Gerät ihn mit einem Key eingetragen hat) und timestamp. Zeig das Alter eines Werts immer mit an.

Namen nur als Text anzeigen

Die Namen von Becken, Dosierprodukten und Aufgaben-Vorlagen haben Menschen eingetippt, bei geteilten Becken auch Mitglieder. Turq entfernt Steuerzeichen und kürzt lange Namen, prüft aber nicht, was drinsteht.

• Zeig sie nur als Text an. Setz sie nie ungeprüft in HTML, Code, Templates oder Befehle ein.
• Gib sie nicht an Sprachassistenten oder Chatbots weiter, die Geräte schalten dürfen. Ein Name kann wie eine Anweisung formuliert sein.
• Arbeite mit IDs, nicht mit Namen. Namen können sich jederzeit ändern und müssen nicht eindeutig sein.

Rezepte

Hier siehst du für verbreitete Systeme, wie die Anfrage aussieht. Für Home Assistant und cURL baut dir die App den Befehl mit deinen IDs; die Beispiele hier zeigen, was darin steckt. Die Namen der Systeme nennen wir nur, damit du das passende Rezept findest. Turq ist mit keinem dieser Projekte verbunden.

Direkt zu: Home Assistant · ESPHome · Node-RED · cURL

turq_bearer: "Bearer <DEIN_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.mein_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: Turq Messwert senden
    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 <DEIN_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(mein_sensor).state;

msg.payload = {
  "timestamp": Date.now(),
  "values": {
    "ph": <Zahl>
  }
};
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=<DEIN_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": <Zahl>}}'

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"}'

Grenzen

Damit die API für alle zuverlässig läuft, begrenzt Turq, wie oft gelesen und wie oft und wie viel geschrieben wird. Die Grenzen gelten für alle gleich, mit und ohne Pro. Feste Zahlen stehen hier bewusst nicht, weil wir sie im Betrieb anpassen. Dein Gerät erfährt alles Nötige aus den Antworten.

• Zu viele Anfragen auf einmal: Die API antwortet mit 429 und RATE_LIMITED. Der Header Retry-After nennt die Sekunden, die du warten sollst.
• Tagesgrenze je Becken: Für Messwerte und Dosierungen gibt es zusätzlich eine Grenze pro Becken und Tag. Erfolgreiche Antworten tragen die Header X-Turq-Daily-Limit (Grenze) und X-Turq-Daily-Remaining (Rest für heute). Bei Messwerten zählt jeder einzelne Wert, nicht jede Anfrage. Der Tag beginnt um 00:00 UTC.
• Grenze erreicht: Dann kommt 429 mit DAILY_LIMIT_REACHED, und Retry-After zählt bis Mitternacht UTC. In der App findest du dazu einen Hinweis bei den Benachrichtigungen.
• Abgelehnte Anfragen und Wiederholungen mit demselben Idempotency-Key zählen nicht mit.
• Lesen hat eigene Grenzen, getrennt vom Schreiben. Auch dort kommt bei zu vielen Anfragen 429 mit RATE_LIMITED und Retry-After. Eine Tagesgrenze je Becken gibt es beim Lesen nicht, und ein 304 zählt wie jede andere Abfrage.

So bleibst du gelassen darunter

• Schick Messwerte im festen Takt statt bei jeder kleinen Änderung. Die Befehle aus der App senden alle 15 Minuten; Wasserwerte ändern sich langsam.
• Bündle die Werte eines Zeitpunkts in einer Anfrage, etwa Temperatur und pH zusammen.
• Wiederhole fehlgeschlagene Anfragen nicht in einer engen Schleife. Halte dich an Retry-After und warte bei Fehlern ohne diesen Header jedes Mal etwas länger.
• Schick Push-Nachrichten nur bei Ereignissen, nicht im Takt.
• Frag Werte nur so oft ab, wie dein Gerät sie braucht. Den passenden Takt findest du unter Lesen.

Doppelte Einträge vermeiden

Gib Schreibanfragen den Header Idempotency-Key mit einem eindeutigen Wert je Ereignis mit, etwa einer UUID, und nimm bei einer Wiederholung derselben Anfrage denselben Wert: Dann trägt Turq das Ereignis nur einmal ein und antwortet beim zweiten Mal mit "replayed": true. Läuft die erste Anfrage noch, kommt 409 mit IDEMPOTENCY_IN_PROGRESS und Retry-After, und derselbe Wert mit anderem Inhalt ergibt 409 mit IDEMPOTENCY_KEY_REUSED.

Fehler

Jeder Fehler hat dasselbe Format: {"error": {"code": …, "message": …, "requestId": …}}. Werte in deinem Code den code aus, nicht den Text in message, denn der kann sich ändern. Die requestId brauchen wir, wenn du dich bei uns meldest.

Referenz

Alle Routen, Felder und Antworten im Detail. Die Basis-URL ist https://api.turq.app/v1; jede Anfrage braucht den Header Authorization: Bearer <Key>, Schreibanfragen schicken JSON. Die Referenz ist auf Englisch und entsteht aus derselben Datei, die du hier herunterladen kannst. Wir gleichen sie bei jeder Änderung automatisch mit dem Code ab.

openapi.yaml herunterladen

OpenAPI 3.1. Du kannst die Datei in dein API-Werkzeug importieren oder dir daraus einen Client erzeugen lassen.

{
  "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
    }
  }
}

Änderungen

Hier steht, was sich an der API ändert, das Neueste oben. Die Hauptversion steht im Pfad (/v1). Neue Felder, Werte und Routen kommen innerhalb von /v1 dazu; dein Code sollte unbekannte Felder und Werte deshalb ignorieren. Änderungen, nach denen laufende Geräte angepasst werden müssen, versuchen wir zu vermeiden und nennen sie hier, sobald sie feststehen. Turq ist ein kleines Projekt: Wir sichern keine Verfügbarkeit und keine Mindestlaufzeit einer Version zu und können die API vorübergehend pausieren.

Hilfe und Feedback

Fragen, Fehler oder Ideen zur API schickst du am besten direkt aus der App: Einstellungen › Hilfe & Feedback. Dort findest du später auch unsere Antwort. Häng bei Fehlern den code, die requestId und das, was dein Gerät gesendet hat, an. Deinen Key brauchen wir nie, schick ihn bitte nicht mit. Und wenn dir eine Route fehlt: Schreib uns, wofür du sie brauchst.

Für die API gelten die Nutzungsbedingungen von Turq und unsere Datenschutzerklärung. Angaben zum Anbieter findest du im Impressum.