Skip to main content
The gumnut-ai/demos repository contains standalone, self-contained example apps that integrate with the Gumnut Photos API. Each demo lives in its own subdirectory, runs against your own Gumnut library using a personal API key, and is small enough to read end-to-end — designed to be forked and adapted.

​
Available demos

​
face-cleanup

Browser-only triage UI for cleaning up a Person’s face cluster. Useful when one Person has been polluted by look-alikes (often a parent/child or sibling pair) and you want to sweep through the worst-fitting faces and reassign them. Single static HTML file — no build step, no server, no dependencies beyond a browser.
This demo mutates your library. Each reassignment calls PATCH /api/faces/{id} and is real and immediate. There is an in-session Undo, but it only walks back history within the open tab.
Endpoints used
  • GET /api/people and GET /api/people/{id} (with cluster_metrics) — header data and candidate Persons.
  • GET /api/faces (with cluster_assignment, paginated) — every face on the subject Person, with distances and the top-K nearest other named Persons. See People and Faces for the suggestion rules.
  • GET /api/assets — parent-asset thumbnails for each face.
  • PATCH /api/faces/{id} — reassignments and detaches.
Demo source and README →

​
geoviewer

Local web app to browse Gumnut assets and inspect their geo metadata (latitude, longitude, city, state, country, country_code, sublocation, place_name, timezone, display_label). Pages of 100 assets load via cursor-based pagination, and an “Only with coordinates” toggle hides assets without lat/lon. A small Hono server proxies the API so your key never leaves the local backend. Endpoints used
  • GET /api/assets — paginated asset list with metadata, proxied through the local server.
  • Asset thumbnails — also proxied so the API key only travels server-side.
Demo source and README →

​
macos-upload-client

Native macOS app that one-way syncs photos and videos from local folders — including NAS and other network volumes — into a Gumnut library. Files are content-addressed by SHA-256 and checked against the library in bulk, so only missing files upload and re-running is always safe. The app runs sandboxed with read-only access to your local files, so it can never modify or delete anything on disk. Every run ends in a plan you approve before anything is sent. Unlike the other demos, this is a full Xcode app (a Swift package plus a SwiftUI app) rather than a browser or local-web tool; it requires Xcode 16+ on macOS 15+.
This demo mutates your library. Each upload calls POST /api/assets and is real and immediate. There is no undo, so review the plan before you approve a run. Confirm the target library in that plan: an all_libraries key can also reach libraries you have joined as a collaborator.
Endpoints used
  • GET /api/users/me — validate the API key.
  • GET /api/libraries — list libraries and confirm the upload target.
  • POST /api/assets/exist — bulk existence check (up to 5,000 checksums per request) so already-present files are skipped.
  • POST /api/assets — multipart upload of each missing file, with file_created_at preserved.
Demo source and README →

​
Running a demo

Each demo has its own README.md with the exact commands. In general:
  1. Clone the demos repo: git clone https://github.com/gumnut-ai/demos.git
  2. cd into the demo’s subdirectory.
  3. Follow the demo’s README — typically a single command (./run.sh, npm run dev, etc.).
You’ll need a Gumnut API key. See API Keys for how to create one. An all_libraries key can reach libraries you own and libraries you join later, subject to your current role and the key’s actions. For a demo that should use a fixed library, choose a selected_libraries key with only that library. Check its target before approving any upload or edit.

​
Contributing a demo

See the contributing notes in the demos repo for the bar new demos should meet.