REST API reference

All /api/v1/… endpoints with examples.

Every UI surface MeshHold ships — the bundled Web UI, the Android app, the Windows tray launcher, the meshhold CLI's --api family — is a client of this REST API. There are no "internal" endpoints; if the Web UI does it, you can do it too with curl.

The base URL is whatever the daemon binds (api.bind in config.yaml, default 127.0.0.1:8080):

http://127.0.0.1:8080/api/v1/...

When api.cert_file / api.key_file are set — or when the daemon auto-generates a self-signed pair on first start — the same prefix moves to https://. The TLS material is also exposed via /system/status so a freshly-paired client can pin the fingerprint.

The surface clusters into six themes — storage, mesh control, comms, networking, integration, observability. Every section below maps to one of them; the diagram is a "you are here" key for the rest of this page.

Authentication

All routes live behind a bearer token. The token is minted by the login endpoint and presented on every subsequent call:

Authorization: Bearer <token>

Five endpoints are open without a token (for bootstrap reasons): /version, /system/status, /auth/login, /auth/logout, /auth/bootstrap-exchange, and /auth/admin/set-password (which enforces its own X-MeshHold-Admin-Token check instead). Inbound webhooks at /hooks/<token> are also exempt — they carry their secret in the path.

POST /auth/login

Exchange the Web UI password for a 24 h bearer.

curl -s http://127.0.0.1:8080/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"password":"hunter2"}'

{"token":"7f3b…","expires_at_ms":1716595200000}

Failure modes: 503 when no password has ever been set, 401 on a wrong password (with a deliberate ~100 ms delay to slow guessing).

POST /auth/bootstrap-exchange

Trade a one-shot bootstrap ticket — minted by the tray launcher via the loopback IPC pipe — for a regular 24 h bearer. The Web UI hits this automatically when it spots a ?bootstrap=… query parameter on first paint. Tickets are single-use and expire 60 s after issue.

POST /auth/admin/set-password

CLI-only. Replaces the Web UI password without knowing the current one. The caller proves authority by presenting the daemon's process-lifetime token from <metadata_dir>/cli-admin.token (mode 0600) in the X-MeshHold-Admin-Token header. There is no web surface for this.

POST /auth/logout

Invalidates the bearer. 204 No Content either way.

Query-string token (?token=…)

A few routes accept the bearer in ?token= instead of the header, for browser primitives that can't set custom headers:

Conventions

• All payloads are JSON unless stated otherwise. Content-Type: application/json is mandatory on writes.
• Time values are milliseconds since epoch as int64, fields suffixed _ms. Durations are Go-style strings ("5s", "2m").
• Vault and node identifiers are opaque strings. Tree-shaped paths (*path routes) are URL-encoded; a leading / is required.
• Errors always look like {"error":"message"} with a non-2xx status. 507 Insufficient Storage is reserved for vault hard-quota hits and carries vault_id / hard_quota / would_be_size alongside the message.

System

The "what is this daemon" surface. Two of these (/version, /system/status) bypass auth so a launcher can introspect before logging in.

GET /system/status is the canonical health probe; the response includes running, has_swarm_key, setup_required, peer_id, listen_addrs, s3_enabled, tls.fingerprint, at_rest.{enabled,provider}, and the active network's {state,id,name}.

Networks

A "network" is a saved (swarm key, bootstrap list) pair. The daemon can hold many but is only ever active in one.

Vaults

Vaults are the storage unit — every file lives in exactly one. Trusted vaults hold a key locally; untrusted vaults read encrypted blocks from peers.

Files

*path segments are URL-encoded and must begin with /.

The upload response is synchronous — the client gets a FileJSON as soon as the bytes are durably on disk and the catalog row is committed. Replication to other nodes is a separate, asynchronous concern driven by the broker; POST /replicate-now kicks it out of its sleep window.

# Upload a file to a vault:
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @./photo.jpg \
  "http://127.0.0.1:8080/api/v1/vaults/$VID/upload/2026/photo.jpg"

# Download with Range — the player uses this verbatim:
curl -s -H "Authorization: Bearer $TOKEN" -H 'Range: bytes=0-1023' \
  "http://127.0.0.1:8080/api/v1/vaults/$VID/stream/movie.mkv" -o head.bin

A vault hard-quota hit returns 507 Insufficient Storage:

{"error":"vault quota exceeded", "vault_id":"…",
 "hard_quota":107374182400, "would_be_size":108221145600}

Per-file metadata, audio + video enrichment

Library (music)

The library endpoints aggregate the audio fingerprinting results across every trusted vault into an iTunes-shaped view. Most accept ?fully_local=true to hide tracks the local node doesn't fully hold.

Network + nodes

Rooms (chat)

room_id is the deterministic hash of the chat key + initial members.

Auto-relay roster (gateway role)

These let an operator manage the rooms this node relays for others.

Calls

Audio/video calls travel over libp2p but are signalled here. The /calls/{id}/media WebSocket carries the actual media frames.

Tunnels, port forwards, system VPN

These three share the underlying multi-hop tunnel substrate; the surface above is different.

Tunnels (HTTP CONNECT proxy)

Port forwards (ssh -L / ssh -R style)

Each entry on GET /forwards returns these fields. New flags shipped with the UPnP rollout:

• open_via_upnp (bool, settable on POST/PATCH) — request a router-side port mapping for the listener (this node's router for forward, the peer's for reverse). Best-effort.
• external_addr (string, read-only) — populated when UPnP succeeded. Forward direction reads it from the local upnp.Manager; reverse reads it from the exit's TunnelListenAck.external_addr. Empty when the mapping wasn't requested or didn't take.

System VPN

The fd-bound start path is JNI-only (Android VpnService delivers a TUN fd). The REST surface here covers stop/stats plus the desktop-Windows start that uses the helper service internally.

Management keys

Mgmt keys gate operations that the swarm-PSK-alone shouldn't authorise: inbound tunnels, call auto-answer, remote mute, push-gateway delivery.

S3 admin

The S3 gateway has its own access-key store, independent of the Web UI bearer.

The endpoints stay available even when the S3 listener is off, so an operator can pre-provision keys before flipping node.s3.enabled.

Profile, contacts, settings

Inbound webhooks

Configured in config.yaml (webhooks: [{token, room_id}, …]) — no runtime CRUD. The endpoint accepts Slack/Mattermost/Discord-shape bodies and posts to the mapped chat room.

A missing or unknown token returns 404, not 401 — there's no information leak about which tokens exist.

Events (SSE)

curl -N -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8080/api/v1/events/stream

: connected

event: chat_message
data: {"type":"chat_message","room_id":"…","sender_node_id":"12D…",
       "ts_ms":1716549300000,"message_type":"TEXT","content_hash":"…","is_self":false}

: keepalive

20 s : keepalive comments keep reverse proxies from reaping idle connections. The wire envelope is the same eventEnvelope shape for every event type — switch on the type field rather than the SSE event: line if you only care about the JSON.

Audit

AI agents

The full "universal AI-agent" surface — Claude Code, OpenCode, etc. It's the largest single subsystem in the API; consult the dedicated developer scenario for an end-to-end walkthrough.

Instance lifecycle:

Sessions:

POST /_mcp/sessions/:sid/approve is the loopback hook the daemon-spawned meshhold _mcp-approve helper calls — not a user-facing endpoint.

Diagnostics

For the Profile page's "Report a problem" button.

503 when the daemon has no writable reports dir (headless install without $HOME).

Status codes