Conventions

Requests and Answers

Bodies are JSON in and JSON out. A read answers 200. A create answers 201. Most responses are objects; a list is an object with the rows under a named field, not a bare array.

Field names are camelCase, with one documented exception: the answer to POST /api/v1/stamp is snake_case, because that payload is shared with the MCP tool surface, whose clients expect that spelling. A client reading signedAt there gets nothing.

Errors

An error carries two required fields.

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

error is a stable machine-readable string. message is for a person and may change. The 403 from scope enforcement adds required_scope.

Status	Meaning
400	The request body is wrong
401	No token, or a token that is not valid
403	The token’s scope is too narrow
404	No such row

Cached Reads

The daemon keeps a local copy of most read data, so it can answer while the network is down. Every cached read adds two fields to its answer.

source is cache when the answer came from the local copy and fresh when it came from the server. syncedAt is the Unix second at which those rows last came from the server, or null if nothing has ever been stored for that read.

Read source before you decide anything about how current the answer is. An answer that carries its own confidence is only useful if somebody reads it.

The Freshness Parameter

Cached reads accept ?freshness=fresh, which forces a trip to the server. Any other value, or none, answers from the cache.

The reads that accept it are:

/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 that go straight to the server mark the cached rows of the kind they changed as stale, so the next read does not answer from a copy made before the write.

Paging

GET /api/v1/verification-log pages with offset and limit, where limit is capped at 100, and filters with direction set to incoming or outgoing.

GET /api/v1/notifications takes limit and unread_only.

No other documented route pages.

Versioning

The document is version 1.0.0 and every route sits under /api/v1/. The tool and MCP endpoints also exist at unprefixed paths for older clients; those stay stable through the v1 lifecycle and are removed only when /api/v2/ ships.

The document spells path parameters two ways — {id} on some routes and :id on others. They mean the same thing. The tables in these pages reproduce each route as the document carries it.