YachtInspect API

Die YachtInspect Export-API liefert die Befunde eines Schiffs — mit Checklisten-Maßnahmen, Kommentarverlauf und Fotos — an Ihre eigenen Systeme: Flottenmanagement-Software, eine Schadendatenbank, das Planungstool einer Werft oder ein BI-Dashboard.

• Basis-URL: https://yachtinspect.quickinspect.me/api
• Maschinenlesbare Spezifikation: /v1/openapi.json (OpenAPI 3 — importierbar in Postman, Insomnia oder Ihren Code-Generator)
• Zugang: nur lesend. Ein Admin schaltet den API-Zugriff für Ihr Unternehmen frei; sprechen Sie Ihren YachtInspect-Ansprechpartner an.

Authentifizierung

Senden Sie den Schlüssel bei jeder Anfrage im Authorization-Header:

curl https://yachtinspect.quickinspect.me/api/v1/findings \
  -H "Authorization: Bearer yi_live_ihr_schluessel"

Schlüssel verwalten Sie in der App unter Listen → API-Zugriff:

Aktion	Wer
API-Zugriff für das Unternehmen ein- oder ausschalten	Admin
Schlüssel erstellen, auflisten und widerrufen	Der Unternehmensinhaber mit der Rolle Key User, oder ein Admin

Beim Erstellen geben Sie dem Schlüssel einen Namen und wählen das Projekt, das er lesen darf. Der Schlüssel wird genau einmal angezeigt — YachtInspect speichert nur einen kryptografischen Hash und kann ihn nicht erneut anzeigen. Behandeln Sie ihn wie ein Passwort. Geht er verloren, widerrufen Sie ihn und erstellen einen neuen. Ein Widerruf wirkt sofort. Ein Unternehmen kann bis zu 20 aktive Schlüssel haben.

Endpunkte

Endpunkt	Daten	Hinweise
GET /v1/project	Das Schiff des Schlüssels	Schiffsidentität, Klassifikation, Antrieb, Besichtigung, Schadenfall und Auftraggeber.
GET /v1/findings	Befunde	Jeder Befund enthält seine Checkliste. Filter siehe unten. Seitenweise.
GET /v1/findings/{id}/comments	Kommentarverlauf eines Befunds	Inklusive der automatischen Statuswechsel-Einträge der App. Seitenweise, älteste zuerst.
GET /v1/findings/{id}/attachments	Fotos und Dokumente eines Befunds, auch die an seinen Kommentaren	Download-Links 15 Minuten gültig.
GET /v1 und GET /v1/openapi.json	Übersicht und Spezifikation	Öffentlich, kein Schlüssel nötig.

Vollständige Anfrage- und Antwortschemata finden Sie im OpenAPI-Dokument.

Was „Maßnahmen" hier bedeutet

Die Folgearbeiten eines Befunds liegen an zwei Stellen, und die API liefert beide:

• Checklistenpunkte sind in jedem Befund als checklist[] enthalten, mit title, done, date_created, date_closed und dem Ersteller. Jeder Befund trägt zusätzlich checklist_total und checklist_open. Checklistenpunkte haben keine eigene ID; index ist ihre Position in der Liste.
• Kommentare kommen von /v1/findings/{id}/comments. Einträge, die die App selbst schreibt — etwa bei einem Statuswechsel — tragen system_triggered: true. Zusammen ergeben sie den vollständigen Verlauf des Befunds.

corrective_measure, start_date, due_date, status und priority sind gewöhnliche Felder des Befunds.

Befunde filtern

GET /v1/findings hat zwei Modi:

Modus	Sortierung	Parameter
Standard	date_created, älteste zuerst	from (inklusive) und to (exklusive), beide auf date_created
Inkrementeller Abgleich	last_edited_date, älteste zuerst	updated_since — Befunde, die ab diesem Zeitpunkt erstellt oder bearbeitet wurden

updated_since lässt sich nicht mit from oder to kombinieren.

Zusätzlich können Sie nach einem dieser Felder filtern:

• status — genau einer von Open, To be reviewed, Closed, Accepted as is, Cancelled, Shipyard confirmed rectification
• system — z. B. Hull
• priority

Zwei davon gleichzeitig ergeben 400. Filtern Sie serverseitig nach einem und grenzen Sie den Rest in Ihrem eigenen Code ein.

Datumsangaben im ISO-8601-Format (2026-09-01 oder 2026-09-01T08:00:00Z).

# Alles, was seit dem letzten Abgleich bearbeitet wurde
curl "https://yachtinspect.quickinspect.me/api/v1/findings?updated_since=2026-09-25T00:00:00Z" \
  -H "Authorization: Bearer yi_live_ihr_schluessel"

In der App ausgeblendete Befunde werden nie zurückgegeben; ihre Kommentare und Anhänge liefern 404.

Seitenweise Abfrage

Listen-Endpunkte liefern höchstens limit Datensätze (Standard 100, Maximum 500) plus einen Cursor:

{
  "data": [ ... ],
  "next_page_token": "eyJ2IjoxLCJhIjoxNz..."
}

Geben Sie next_page_token als page_token zurück, um die nächste Seite zu erhalten. Fragen Sie weiter ab, bis next_page_token null ist. Eine Seite kann weniger als limit Datensätze enthalten und trotzdem eine Folgeseite haben (ausgeblendete Befunde werden nach dem Lesen der Seite entfernt) — eine kurze Seite bedeutet also nicht, dass Sie fertig sind. Tokens sind undurchsichtig — nicht zerlegen oder selbst bauen.

Alle Zeitstempel sind ISO-8601 in UTC, Feldnamen stabil in snake_case.

Anhänge

GET /v1/findings/{id}/attachments listet alle Dateien eines Befunds. Das Feld source sagt, woher eine Datei stammt:

source	Was	Reihenfolge
location_details_image	Das Ortsbild des Befunds	Zuerst
findings_file	Die Fotos und Dokumente des Befunds	Wie in App und Berichten
comment	Dateien an den Kommentaren des Befunds: Foto, Video, Sprachnachricht oder Dokument (content_kind ist image, video, audio oder file)	Älteste Kommentare zuerst

Kommentardateien tragen die comment_id ihres Kommentars, sodass Sie sie dem richtigen Eintrag aus /comments zuordnen können. In /comments selbst zeigen has_image, has_video, has_audio und has_file, welche Kommentare Dateien haben.

Jede Zeile hat eine download_url, die 15 Minuten gültig ist (download_url_expires_at) — laden Sie Dateien also während des Abgleichs herunter, statt die Links zu speichern.

Kann ein Link nicht erstellt werden, hat die Zeile download_url: null und einen download_error; der Rest der Liste wird trotzdem geliefert. Dieser Endpunkt hat keinen Cursor: limit begrenzt die Zeilen über alle Quellen hinweg, und truncated: true zeigt an, dass etwas weggelassen wurde.

Datenschutz

Die API liefert die Anzeigenamen der Personen, die erstellt, bearbeitet oder kommentiert haben — nie E-Mail-Adressen oder Profilbilder. /v1/project enthält keine Budget- oder Stundenangaben.

Ratenbegrenzung

Jeder Schlüssel darf 60 Anfragen pro Minute und 10.000 pro Tag stellen. Darüber antwortet die API mit 429 und einem Retry-After-Header in Sekunden — so lange warten, dann erneut versuchen. Nutzen Sie limit=500 für Komplettexporte, um die Zahl der Anfragen gering zu halten. Höhere Limits auf Anfrage.

Fehler

Jeder Fehler hat dieselbe Form:

{ "error": { "code": "unauthorized", "message": "Invalid API key." } }

HTTP	code	Bedeutung
400	invalid_request	Ein Parameter ist fehlerhaft, oder zwei Filter wurden kombiniert.
401	unauthorized	Schlüssel fehlt, ist fehlerhaft, unbekannt oder widerrufen.
403	forbidden	API-Zugriff ist für das Unternehmen ausgeschaltet, oder das Projekt des Schlüssels existiert nicht mehr bzw. gehört inzwischen einem anderen Unternehmen.
404	not_found	Unbekannter Endpunkt, oder der Befund gehört nicht zum Projekt dieses Schlüssels.
429	rate_limited	Zu viele Anfragen — Retry-After beachten.
500	internal	Fehler auf unserer Seite. Mit Backoff erneut versuchen.

Sicherheit

• Schlüssel werden nur als SHA-256-Hash gespeichert; der Klartext-Schlüssel wird nie abgelegt.
• Jede API-Anfrage sowie jede Erstellung und jeder Widerruf eines Schlüssels wird im Audit-Trail Ihres Unternehmens protokolliert.
• Die API ist nur lesend. Sie kann in YachtInspect nichts anlegen, ändern oder löschen.