Konventionen

Anfragen und Antworten

Rümpfe sind JSON hinein und JSON hinaus. Ein Lesezugriff antwortet mit 200. Ein Anlegen antwortet mit 201. Die meisten Antworten sind Objekte; eine Liste ist ein Objekt mit den Zeilen unter einem benannten Feld, kein nacktes Array.

Die Namen der Antwortfelder sind camelCase, mit einer dokumentierten Ausnahme: Die Antwort auf POST /api/v1/stamp ist snake_case, weil dieser Rumpf mit der MCP-Werkzeugoberfläche geteilt wird, deren Clients diese Schreibweise erwarten. Ein Client, der dort signedAt liest, bekommt nichts.

Anfragerümpfe und Query-Parameter unterliegen dieser Regel nicht, und mehrere davon sind snake_case — file_path bei POST /api/v1/stamp, notification_ids bei DELETE /api/v1/notifications, unread_only bei GET /api/v1/notifications. Sende den Namen, den das Dokument trägt; ein camelCased Name wird stillschweigend verworfen.

Fehler

Ein Fehler trägt zwei erforderliche Felder.

{ "error": "invalid_input", "message": "Provide exactly 3 words" }

error ist eine stabile, maschinenlesbare Zeichenkette. message ist für Menschen gedacht und kann sich ändern. Das 403 aus der Berechtigungsdurchsetzung ergänzt required_scope.

Status	Bedeutung
400	Der Anfragerumpf ist falsch
401	Kein Token, oder ein Token, das nicht gültig ist
403	Die Berechtigung des Tokens ist zu eng
404	Keine solche Zeile

Zwischengespeicherte Lesezugriffe

Der Dienst hält für die meisten Lesedaten eine lokale Kopie vor, damit er auch antworten kann, wenn das Netz ausfällt. Jeder zwischengespeicherte Lesezugriff ergänzt seine Antwort um zwei Felder.

source ist cache, wenn die Antwort aus der lokalen Kopie kam, und fresh, wenn sie vom Server kam. syncedAt ist die Unix-Sekunde, zu der diese Zeilen zuletzt vom Server kamen, oder null, wenn für diesen Lesezugriff noch nie etwas gespeichert wurde.

Lies source, bevor du dir eine Meinung darüber bildest, wie aktuell die Antwort ist. Eine Antwort, die ihre eigene Verlässlichkeit mitbringt, nützt nur, wenn sie auch gelesen wird.

Der Aktualitätsparameter

Zwischengespeicherte Lesezugriffe nehmen ?freshness=fresh entgegen, was eine Fahrt zum Server erzwingt. Jeder andere Wert, oder keiner, antwortet aus dem Zwischenspeicher.

Die Lesezugriffe, die ihn annehmen, sind:

/api/v1/api-tokens              /api/v1/org/activity
/api/v1/devices                 /api/v1/org/alerts
/api/v1/emails                  /api/v1/org/analytics/dashboard
/api/v1/exports                 /api/v1/org/analytics/trends
/api/v1/external-members        /api/v1/org/groups
/api/v1/guest-codes             /api/v1/org/members
/api/v1/invitations             /api/v1/preferences
/api/v1/notifications           /api/v1/presets
/api/v1/open-links              /api/v1/profile
/api/v1/open-links/requests     /api/v1/sessions
/api/v1/tags                    /api/v1/trust-cards
/api/v1/verification-log

Schreibzugriffe, die direkt zum Server gehen, markieren die zwischengespeicherten Zeilen der betroffenen Art als veraltet, sodass der nächste Lesezugriff nicht aus einer Kopie antwortet, die vor dem Schreibzugriff entstanden ist.

Seitenweise Abfrage

GET /api/v1/verification-log blättert mit offset und limit, wobei limit auf 100 gedeckelt ist, und filtert mit direction, gesetzt auf incoming oder outgoing.

GET /api/v1/notifications nimmt limit und unread_only entgegen.

Keine andere dokumentierte Route blättert seitenweise.

Versionierung

Das Dokument ist Version 1.0.0, und jede Route liegt unter /api/v1/. Die Werkzeug- und MCP-Endpunkte existieren für ältere Clients zusätzlich unter unpräfigierten Pfaden; die bleiben über den gesamten v1-Lebenszyklus stabil und werden erst entfernt, wenn /api/v2/ erscheint.

Das Dokument schreibt Pfadparameter auf zwei Arten — {id} bei manchen Routen und :id bei anderen. Sie meinen dasselbe. Die Tabellen auf diesen Seiten geben jede Route so wieder, wie das Dokument sie trägt.