← Dashboard · Docs ·Api Reference

Grove API Reference

Base URL: http://:5678

Authentication

Most endpoints require one of:

Session cookie — from dashboard login (POST /login)
Peer secret — X-Grove-Secret: header (for peer-to-peer APIs)

Public endpoints (no auth): /login, /api/version, /api/pubkey, /api/source, /invite/, /manifest.json, /sw.js

Core APIs

`GET /api/version`

Returns build info. Public (no auth).


{"build": "abc123", "build_time": "2026-03-28T...", "started": "2026-03-28T...", "grove_py": 255707, "web_py": 575495}

`GET /api/health`

Cell health check. Requires peer secret.


{"ok": true, "disk_free_gb": 333.2, "chunks": 142, "peers": 5}

`GET /api/pubkey`

Returns cell's public signing key. Public.


{"signing_pubkey": "1ChOy...", "x25519_pubkey": "abc..."}

`GET /api/status`

Cell status overview. Requires auth.


{"chunks": 142, "peers": 5, "manifests": 47, "bounty": 1250.5}

File Operations

`POST /upload`

Upload files to GROVE_HOME. Session auth. Multipart form with files field.

`POST /download/`

Download a file by manifest name. Session auth. Returns file content.

`GET /view/`

Inline view of a file (for images, video, audio preview). Session auth.

`GET /preview?path=`

Serve a file from GROVE_HOME for inline preview. Session auth.

`POST /sync`

Manually sync a specific file to peers. Form: path=. Session auth.

`POST /sync-all`

Trigger sync of all files to peers. Session auth.

`POST /archive-by-path`

Remove local copy of a file (keep on peers). Form: path=. Session auth.

`POST /restore/`

Restore a file from peers (download chunks back). Session auth.

Peer-to-Peer APIs

These are called between cells during sync. All require X-Grove-Secret header.

`GET /api/chunk-inventory`

Returns list of all chunk hashes this cell holds.


{"chunks": ["abc123...", "def456..."]}

`POST /api/receive-chunks`

Push chunks to this cell. Multipart form: each field is {hash}: (hash, data, "application/octet-stream").

`GET /api/serve-chunk-peer/`

Download a specific chunk by hash.

`POST /api/delete-chunks`

Delete chunks from this cell. JSON body: {"hashes": ["abc...", "def..."]}.

`GET /api/manifest-inventory`

Returns list of all manifest filenames.


{"manifests": ["photo.jpg.a1b2c3d4.json", ...]}

`POST /api/receive-manifests`

Push manifests to this cell. JSON body with manifest data.

`GET /api/serve-manifest/`

Download a specific manifest file.

`POST /api/receive-grant`

Push a share grant to this cell. JSON body with grant data.

`GET /api/grants-for/`

Get grants created by a specific pubkey (for sync).

`POST /api/revoke-grant`

Revoke a previously sent grant.

Sharing APIs

`POST /share`

Share file(s) with peers. Form: manifest=, peers=,. Session auth.

`POST /unshare`

Revoke sharing. Form: manifest=, peers=. Session auth.

`POST /reshare`

Re-share updated version of a file. Form: manifest=. Session auth.

`POST /api/shared-folders`

Get/set auto-share folder configuration. Session auth.

`GET /feed`

HTML feed page showing files shared with you. Session auth.

Network APIs

`GET /api/replication-status`

Replication health for all peers.


{"peers": [{"user": "nookman", "status": "online", "chunks": 89, ...}], "total_chunks": 142}

`GET /api/route-speeds`

All routes to all peers with recorded speeds and selected route.


{"peers": [{"user": "nookman", "routes": [...], "selected_route": "100.96.243.69"}], "last_benchmark": "..."}

`POST /api/benchmark`

Trigger manual route benchmark (pushes/pulls test chunks to all peers).

`GET /api/opp-sync-status`

Background sync status.


{"active": false, "interval_seconds": 300}

`GET /api/relay/status`

Relay connection status.


{"connected": true, "relay_url": "ws://...", "peers_online": ["pubkey1", ...]}

`GET /api/peer-speeds`

Raw peer speed measurements.

`GET /api/peer-health`

Peer uptime/reliability data.

Peer Management

`POST /peers/add`

Add a peer. Form: host=, port=5678, user=. Session auth.

`POST /peers/remove`

Remove a peer. Form: host=, mode=list-only|and-files. Returns JSON.

`POST /peers/favorite`

Toggle favorite status. Form: user=. Session auth.

`POST /friends/add`

Promote peer to friend. Form: host=. Session auth.

`POST /friends/remove`

Demote friend to peer. Form: host=. Session auth.

Invite System

`POST /api/invite/create`

Create an invite link. JSON body: {"message": "Welcome!", "name": "...", "bounty": 0}.


{"ok": true, "token_id": "abc...", "url": "https://grove.nook.website/invite/abc..."}

`GET /api/invite/list`

List all invites with status.

`GET /invite/`

Invite landing page (browser) or install script (curl/wget).

`POST /invite//download`

Download install script with user's chosen name baked in.

`POST /api/invite//accept`

Accept an invite (called by install script). JSON: {"pubkey": "...", "self_name": "..."}.

AI APIs

`GET /api/ai/status`

Local AI availability, hardware, model info.


{"available": true, "model": "nemotron-3-nano-4b-q4_k_m.gguf", "hardware": {"chip": "Apple M4", "gpu": "metal"}, "status": "idle"}

`POST /api/ai/chat`

Send a message to local AI. JSON: {"message": "Hello", "system": "optional system prompt"}. Returns streaming response.

`GET /api/ai/network`

Find AI-capable peers in the fleet.

`POST /api/ai/proxy`

Proxy a chat request to a peer's AI.

Settings

`GET /api/settings`

Current cell settings.

`POST /api/settings`

Update settings. JSON body with fields to change.

`POST /api/settings/password`

Change dashboard password. JSON: {"current": "...", "new": "..."}.

Chat

`GET /api/chat`

Get chat conversations and messages.

`POST /api/chat-message`

Send an encrypted chat message. JSON: {"peer": "pubkey", "message": "..."}.

`POST /api/chat/delete`

Delete a chat message.

Maintenance

`POST /api/gc`

Run garbage collection (remove orphaned chunks).

`POST /api/prune-excess`

Remove over-replicated chunks from peers.

`GET /api/prune-preview`

Preview what pruning would remove.

`GET /api/backup-keys`

Download encryption keys as ZIP (for backup).

`POST /api/restore-keys`

Restore keys from backup ZIP.