Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 Persons.
  • 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 →

​
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 — the key is scoped to your account, and demos only ever see data from libraries you own.

​
Contributing a demo

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