Convenciones

Solicitudes y respuestas

Los cuerpos son JSON de entrada y JSON de salida. Una lectura responde 200. Una creación responde 201. La mayoría de las respuestas son objetos; una lista es un objeto con las filas bajo un campo con nombre, no un array a secas.

Los nombres de campo de respuesta son camelCase, con una excepción documentada: la respuesta a POST /api/v1/stamp es snake_case, porque ese payload se comparte con la superficie de herramientas MCP, cuyos clientes esperan esa forma de escribirlo. Un cliente que lea signedAt ahí no obtiene nada.

Los cuerpos de solicitud y los parámetros de consulta no están sujetos a esa regla y varios son snake_case — file_path en POST /api/v1/stamp, notification_ids en DELETE /api/v1/notifications, unread_only en GET /api/v1/notifications. Envía el nombre que lleva el documento; uno en camelCase se descarta en silencio.

Errores

Un error lleva dos campos obligatorios.

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

error es una cadena estable y legible por máquina. message es para una persona y puede cambiar. El 403 de la aplicación de permisos añade required_scope.

Estado	Significado
400	El cuerpo de la solicitud está mal
401	Sin token, o un token que no es válido
403	El permiso del token es demasiado estrecho
404	No existe esa fila

Lecturas en caché

El daemon guarda una copia local de la mayoría de los datos de lectura, para poder responder mientras la red está caída. Cada lectura en caché añade dos campos a su respuesta.

source es cache cuando la respuesta vino de la copia local y fresh cuando vino del servidor. syncedAt es el segundo Unix en el que esas filas llegaron del servidor por última vez, o null si nunca se ha guardado nada para esa lectura.

Lee source antes de decidir nada sobre lo actual que es la respuesta. Una respuesta que lleva su propia confianza solo sirve si alguien la lee.

El parámetro de frescura

Las lecturas en caché aceptan ?freshness=fresh, que fuerza un viaje al servidor. Cualquier otro valor, o ninguno, responde desde la caché.

Las lecturas que lo aceptan son:

/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

Las escrituras que van directas al servidor marcan como obsoletas las filas en caché del tipo que cambiaron, así que la siguiente lectura no responde desde una copia hecha antes de la escritura.

Paginación

GET /api/v1/verification-log pagina con offset y limit, donde limit tiene un tope de 100, y filtra con direction fijado a incoming o outgoing.

GET /api/v1/notifications toma limit y unread_only.

Ninguna otra ruta documentada pagina.

Versionado

El documento es la versión 1.0.0 y cada ruta está bajo /api/v1/. Los puntos finales de herramienta y MCP también existen en rutas sin prefijo para clientes más antiguos; esas se mantienen estables durante todo el ciclo de vida de v1 y solo se eliminan cuando llega /api/v2/.

El documento escribe los parámetros de ruta de dos formas — {id} en algunas rutas y :id en otras. Significan lo mismo. Las tablas de estas páginas reproducen cada ruta tal como la lleva el documento.