Nodus
Reference

Relay REST API

Every HTTP endpoint exposed by the Go Relay.

The Relay registers routes on Go's net/http ServeMux (method + pattern routing). Routes marked session require an authenticated session cookie or bearer token; node routes require a stateless Ed25519 request signature (X-Nodus-*, valid for a 5-minute window). All routes except /health and /ws are only registered when SQLite is available.

Health

MethodPathAuthPurpose
GET/healthopenLiveness/readiness; reports Postgres + Redis status

Auth and sessions

MethodPathAuthPurpose
POST/auth/registeropenCreate an account (Argon2id password)
POST/auth/loginopenLogin; issues a session
GET/auth/sessionsessionReturn the current session/account
POST/auth/logoutopenRevoke the current session
POST/auth/passwordsessionChange password; rotates the session
POST/auth/logout-allsessionRevoke all sessions except the current device
POST/auth/recovery/challengeopenIssue a signed recovery challenge
POST/auth/recoveryopenComplete recovery via a signed challenge

Devices

MethodPathAuthPurpose
POST/devices/registersessionRegister a device
GET/devicessessionList devices
DELETE/devices/{id}sessionRevoke a device and its sessions
PATCH/devices/{id}sessionRename a device
POST/devices/push-tokensessionRegister a mobile push token
DELETE/devices/push-tokensessionUnregister a mobile push token
POST/devices/web-pushsessionRegister a browser PushSubscription
DELETE/devices/web-pushsessionUnregister a browser PushSubscription
POST/devices/{device_id}/pingsessionSend a WS ping; await pong

Account recovery identity

MethodPathAuthPurpose
PUT/account/recoverysessionEnroll/rotate the recovery public key

Storage nodes

MethodPathAuthPurpose
POST/nodes/registersessionRegister a node
GET/nodessessionList nodes
PATCH/nodes/{node_id}sessionRename a node
POST/nodes/{node_id}/pingsessionWS reachability probe
GET/nodes/verifyopenPre-flight a discovered node URL against the Relay

Catalog

MethodPathAuthPurpose
GET/filessessionFile catalog
GET/folderssessionFolder tree
GET/activitiessessionAccount activity feed
GET/envelopessessionKey envelopes
GET/envelopes/summarysessionPer-recipient coverage counts
GET/envelopes/exportsessionCiphertext-only envelope backup
GET/folder-envelopessessionBulk folder-key envelopes

Tombstones and conflicts

MethodPathAuthPurpose
GET/tombstonessessionList soft-deleted entities
DELETE/tombstones/{entity_type}/{entity_id}sessionPermanently purge
POST/tombstones/{entity_type}/{entity_id}/restoresessionRestore a soft-deleted entity
POST/files/{file_id}/conflicts/resolvesessionResolve a conflict over HTTP

Pairing

MethodPathAuthPurpose
POST/pairing/sessionssessionIssue a device-bound pairing token; WS-pushed to the node
POST/pairing/sessions/verifyopenNode's lazy token-verification fallback
POST/pairing/codessessionMint a bootstrap pairing code
POST/pairing/codes/redeemopenConsume a code; register a node

Rebuild, buffer, shards

MethodPathAuthPurpose
POST/rebuildsessionTrigger a full snapshot / Relay rebuild
POST/buffer/uploadsessionPath C: upload an encrypted shard while the node is offline
GET/shards/{object_id}sessionRelay-mediated shard download fallback
GET/node/shards/{object_id}nodeNode→Relay peer-repair shard fetch
GET/buffer/fetchnodeNode pulls a buffered shard with a single-use token

WebSocket

MethodPathAuthPurpose
GET/wssession or node challengePresence, sync events, push, pairing-token push, relay-mediated shard bytes

Storage Node CLI

Commands, flags, the interactive menu, and the running shell.

Relay WebSocket

The /ws gateway: authentication, presence, and message families.

On this page

HealthAuth and sessionsDevicesAccount recovery identityStorage nodesCatalogTombstones and conflictsPairingRebuild, buffer, shardsWebSocketRelated