Conventies

Verzoeken en antwoorden

Bodies zijn JSON in en JSON uit. Een read antwoordt 200. Een create antwoordt 201. De meeste antwoorden zijn objecten; een lijst is een object met de rijen onder een benoemd veld, geen kale array.

Veldnamen in het antwoord zijn camelCase, met één gedocumenteerde uitzondering: het antwoord op POST /api/v1/stamp is snake_case, omdat die payload wordt gedeeld met het MCP-toolvlak, waarvan de clients die spelling verwachten. Een client die daar signedAt leest, krijgt niets.

Requestbodies en queryparameters vallen niet onder die regel, en verscheidene zijn snake_case — file_path op POST /api/v1/stamp, notification_ids op DELETE /api/v1/notifications, unread_only op GET /api/v1/notifications. Stuur de naam die het document draagt; een camelCase-variant wordt stilzwijgend genegeerd.

Fouten

Een fout draagt twee verplichte velden.

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

error is een stabiele, machineleesbare tekenreeks. message is voor een mens en kan veranderen. De 403 van scopehandhaving voegt required_scope toe.

Status	Betekenis
400	De requestbody klopt niet
401	Geen token, of een token dat niet geldig is
403	De scope van het token is te smal
404	Geen zo’n rij

Gecachete reads

De daemon houdt een lokale kopie bij van de meeste leesbare gegevens, zodat hij kan antwoorden terwijl het netwerk uitligt. Elke gecachete read voegt twee velden aan zijn antwoord toe.

source is cache wanneer het antwoord uit de lokale kopie kwam en fresh wanneer het van de server kwam. syncedAt is de Unix-seconde waarop die rijen voor het laatst van de server kwamen, of null als er voor die read nog nooit iets is opgeslagen.

Lees source voordat je iets beslist over hoe actueel het antwoord is. Een antwoord dat zijn eigen betrouwbaarheid meedraagt, heeft alleen nut als iemand die ook leest.

De freshness-parameter

Gecachete reads accepteren ?freshness=fresh, wat een reis naar de server afdwingt. Elke andere waarde, of geen, antwoordt vanuit de cache.

De reads die dit accepteren, zijn:

/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

Writes die rechtstreeks naar de server gaan, markeren de gecachete rijen van het type dat ze veranderden als verouderd, zodat de volgende read niet antwoordt vanuit een kopie die vóór de write is gemaakt.

Paginering

GET /api/v1/verification-log pagineert met offset en limit, waarbij limit een plafond heeft van 100, en filtert met direction op incoming of outgoing.

GET /api/v1/notifications neemt limit en unread_only.

Geen andere gedocumenteerde route pagineert.

Versiebeheer

Het document is versie 1.0.0 en elke route valt onder /api/v1/. De tool- en MCP-eindpunten bestaan ook op paden zonder voorvoegsel, voor oudere clients; die blijven stabiel gedurende de levensduur van v1 en worden pas verwijderd zodra /api/v2/ uitkomt.

Het document spelt padparameters op twee manieren — {id} op sommige routes en :id op andere. Ze betekenen hetzelfde. De tabellen op deze pagina’s geven elke route weer zoals het document haar draagt.