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.

CLI tokens — …/auth/cli-tokens

Long-lived bearer credentials for the meshhold auth CLI. Unlike the 24 h session bearer above, these are persisted on the daemon and survive restarts, so a co-located CLI can save one to ~/.meshhold/cli.json and keep using it. They are bearer-gated (the caller must already hold a valid session bearer — via password login or the admin-token exchange — before minting one), independent of the Web UI password, and stored only as their SHA-256.

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 /.

Folders

A vault's folders are otherwise implied by the paths of the files in them, which leaves an empty one nowhere to exist. A folder created through these routes is a catalog entry of its own — no blocks, no size, no content hash — so it replicates to peers and survives being empty. It appears in GET /files with is_dir: true; skip those rows when you want files.

Two things it deliberately is not: an object over S3 (that protocol has no directories, so folder rows are not listed and GET/HEAD on one is NoSuchKey), and a renameable thing — a folder is the shape of the paths beneath it, so moving one would be a rewrite of every file below.

Writing a file in pieces

POST /upload needs a Content-Length, which a filesystem does not have: it learns how long a file is by being told it is finished. So a mount, and Android's picker, write through a session instead.

Offsets are explicit rather than implied by request order, because that is what the caller actually has, and because it lets the daemon catch an out-of-order write where it can answer instead of storing the file wrong.

A session that goes untouched is abandoned after node.write_session_ttl (default 2 minutes) — it holds its path's lock for its whole life, so one that is never collected would block every later write to that path. The deadline comes back as ttl_ms when you open one. An expired handle answers 410 Gone, meaning "open a new one", not a generic failure. A refused chunk ends the session, so a client that ignored the error cannot commit the fragment.

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

Pictures

GET /photos returns {photos: [...], next_cursor, pending}. Three fields repay attention:

• taken_at_ms is absent rather than falling back to modified_at_ms. For a photograph the file's mtime is usually the day it was copied, so a date grouping built on it looks plausible and is wrong.
• meta_read separates "this picture carries no date" from "nobody has read it yet" — the difference between a permanent Undated section and one that empties while you watch. pending counts the second kind.
• has_gps arrives even when lat/lon do not, so a client can warn that an album carries location data without being handed the location.

local is three-valued: true/false say whether every block is on this node, and absent means the listing spent its lookup budget and stopped asking. Absent must not be drawn as "elsewhere".

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.

Exit routing (split-tunnel & multi-exit)

The routing model behind the system VPN — Exit routing — is fully REST-driven (the Exit nodes section is a thin client over these). Changes persist to the vpn: config block and apply live to a running session (no reconnect).

Management keys

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

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, Gemini CLI. 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