Skip to content

routes

diapason.mesh.routes

REST API for the device mesh.

Everything here is authenticated by the local API key EXCEPT one route: POST /v1/mesh/pairings/redeem. A device being enrolled does not have the key yet — that is the whole point of enrolment — so it authenticates with the one-time pairing token instead, exactly as Succès sync already does. That route is rate-limited on its own bucket (see _OPEN_MESH_ROUTES in the auth middleware), because it is the mesh's front door. It was not, for a while: the limiter ran only for paths that require the API key, so opening a route to unauthenticated devices silently opened it to unlimited traffic too.

ack_commands(body)

A device reporting what it did with what it collected.

Without this half a polled command would stay PENDING forever and the user would never learn whether it happened — which is the same failure as claiming it did.

announce(appState='')

Push our own presence to every peer we know how to reach.

Behind the key wall: this is the local app asking to be seen, not a stranger asking to be believed.

command_history(limit=50)

Recent commands, newest first (spec §43).

declare_capabilities(device_id, body)

Record what a device claims. The grant is computed, never taken.

deliver_command(body)

Receive a command from another device.

Outside the API-key wall on purpose, and NOT unauthenticated: the envelope's Ed25519 signature is the credential, checked against the key recorded when the sender was paired. A stronger proof than a shared secret, since it also binds the exact arguments.

forget_device(device_id)

Erase a device outright — the only way back from revocation.

inbox(drain=True)

What the local shell should open or show, oldest first.

Polled by the desktop app; draining on read means a screen is opened once, not on every poll.

list_tools()

The remote catalogue, as the assistant's router should advertise it.

poll_commands(body)

A device asking for whatever is waiting for it.

Outside the API-key wall, like the other two device-signed surfaces. This is how a phone joins the mesh at all: it has no address to be dialled at, so it comes to fetch. The poll doubles as its heartbeat — asking for your commands proves you are awake better than any beacon.

receive_presence(body)

A paired device announcing itself.

Outside the API-key wall for the same reason as /commands/deliver: a device that joined this fleet never receives this machine's key, and its Ed25519 signature is a stronger credential anyway — it binds the exact claim, including the address commands will later be sent to.

redeem_pairing(body)

Enrol a device that presents a valid invitation.

Deliberately outside the API-key wall: the joining device has no key. The invitation is the credential, and it is single-use and short-lived.

send_command(body)

Send a command to another device. Authenticated by the local API key: this is the assistant or the UI on THIS machine asking.

whoami()

This installation's own identity — public half only.