Conventions

Requêtes et réponses

Les corps sont en JSON, dans les deux sens. Une lecture répond 200. Une création répond 201. La plupart des réponses sont des objets ; une liste est un objet avec les lignes sous un champ nommé, pas un tableau nu.

Les noms de champs de réponse sont en camelCase, avec une exception documentée : la réponse à POST /api/v1/stamp est en snake_case, parce que cette charge utile est partagée avec la surface d’outils MCP, dont les clients attendent cette orthographe. Un client qui lit signedAt là-bas n’obtient rien.

Les corps de requête et les paramètres de requête ne sont pas soumis à cette règle, et plusieurs sont en snake_case — file_path sur POST /api/v1/stamp, notification_ids sur DELETE /api/v1/notifications, unread_only sur GET /api/v1/notifications. Envoie le nom que porte le document ; une version en camelCase est ignorée silencieusement.

Erreurs

Une erreur porte deux champs obligatoires.

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

error est une chaîne stable et lisible par une machine. message est destiné à une personne et peut changer. Le 403 renvoyé par l’application des portées ajoute required_scope.

Statut	Signification
400	Le corps de la requête est incorrect
401	Aucun jeton, ou un jeton invalide
403	La portée du jeton est trop étroite
404	Aucune ligne de ce type

Lectures en cache

Le démon conserve une copie locale de la plupart des données en lecture, pour pouvoir répondre pendant une coupure réseau. Chaque lecture en cache ajoute deux champs à sa réponse.

source vaut cache quand la réponse vient de la copie locale, et fresh quand elle vient du serveur. syncedAt est la seconde Unix à laquelle ces lignes ont été mises à jour depuis le serveur pour la dernière fois, ou null si rien n’a jamais été stocké pour cette lecture.

Lis source avant de tirer une conclusion sur la fraîcheur de la réponse. Une réponse qui porte sa propre confiance n’est utile que si quelqu’un la lit.

Le paramètre de fraîcheur

Les lectures en cache acceptent ?freshness=fresh, qui force un aller-retour vers le serveur. Toute autre valeur, ou son absence, répond depuis le cache.

Les lectures qui l’acceptent sont :

/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

Les écritures qui vont directement au serveur marquent les lignes en cache du type qu’elles ont modifié comme périmées, pour que la lecture suivante ne réponde pas depuis une copie antérieure à l’écriture.

Pagination

GET /api/v1/verification-log pagine avec offset et limit, où limit est plafonné à 100, et filtre avec direction réglé sur incoming ou outgoing.

GET /api/v1/notifications accepte limit et unread_only.

Aucune autre route documentée ne pagine.

Versionnage

Le document est en version 1.0.0 et chaque route se trouve sous /api/v1/. Les points de terminaison outils et MCP existent aussi sous des chemins sans préfixe pour les clients plus anciens ; ils restent stables pendant tout le cycle de vie de v1 et ne sont retirés qu’au lancement de /api/v2/.

Le document écrit les paramètres de chemin de deux façons — {id} sur certaines routes et :id sur d’autres. Ils signifient la même chose. Les tableaux de ces pages reproduisent chaque route telle que le document la porte.