Convenzioni

Richieste e risposte

I corpi sono JSON in entrata e JSON in uscita. Una lettura risponde 200. Una creazione risponde 201. La maggior parte delle risposte sono oggetti; un elenco è un oggetto con le righe sotto un campo con nome, non un array nudo.

I nomi dei campi nelle risposte sono in camelCase, con un’eccezione documentata: la risposta a POST /api/v1/stamp è in snake_case, perché quel payload è condiviso con la superficie degli strumenti MCP, i cui client si aspettano quella grafia. Un client che legge signedAt lì non ottiene nulla.

I corpi delle richieste e i parametri di query non sono soggetti a quella regola e diversi sono in snake_case — file_path su POST /api/v1/stamp, notification_ids su DELETE /api/v1/notifications, unread_only su GET /api/v1/notifications. Invia il nome che porta il documento; uno in camelCase viene scartato in silenzio.

Errori

Un errore porta due campi obbligatori.

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

error è una stringa stabile e leggibile da una macchina. message è per una persona e può cambiare. Il 403 dall’applicazione dello scope aggiunge required_scope.

Stato	Significato
400	Il corpo della richiesta è sbagliato
401	Nessun token, o un token non valido
403	Lo scope del token è troppo stretto
404	Nessuna riga simile

Letture in cache

Il daemon conserva una copia locale della maggior parte dei dati di lettura, così può rispondere mentre la rete è giù. Ogni lettura in cache aggiunge due campi alla sua risposta.

source è cache quando la risposta viene dalla copia locale e fresh quando viene dal server. syncedAt è il secondo Unix in cui quelle righe sono arrivate dal server l’ultima volta, o null se non è mai stato memorizzato nulla per quella lettura.

Leggi source prima di decidere qualsiasi cosa su quanto sia attuale la risposta. Una risposta che porta la propria affidabilità è utile solo se qualcuno la legge.

Il parametro di freschezza

Le letture in cache accettano ?freshness=fresh, che forza un viaggio verso il server. Qualsiasi altro valore, o nessuno, risponde dalla cache.

Le letture che lo accettano sono:

/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

Le scritture che vanno direttamente al server contrassegnano come obsolete le righe in cache del tipo che hanno cambiato, così la lettura successiva non risponde da una copia fatta prima della scrittura.

Paginazione

GET /api/v1/verification-log pagina con offset e limit, dove limit è limitato a 100, e filtra con direction impostato su incoming o outgoing.

GET /api/v1/notifications accetta limit e unread_only.

Nessun’altra rotta documentata pagina.

Versionamento

Il documento è alla versione 1.0.0 e ogni rotta sta sotto /api/v1/. Gli endpoint dello strumento e di MCP esistono anche su percorsi senza prefisso per i client più vecchi; questi restano stabili per tutto il ciclo di vita di v1 e vengono rimossi solo quando esce /api/v2/.

Il documento scrive i parametri di percorso in due modi — {id} su alcune rotte e :id su altre. Significano la stessa cosa. Le tabelle in queste pagine riproducono ogni rotta come la porta il documento.