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

# Demos

> Standalone reference integrations that consume the Gumnut Photos API

The [`gumnut-ai/demos`](https://github.com/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.

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

**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 →](https://github.com/gumnut-ai/demos/tree/main/face-cleanup)

### 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](https://hono.dev) 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 →](https://github.com/gumnut-ai/demos/tree/main/geoviewer)

## Running a demo

Each demo has its own `README.md` with the exact commands. In general:

1. Clone the [demos repo](https://github.com/gumnut-ai/demos): `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](/guides/authentication/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](https://github.com/gumnut-ai/demos#contributing) in the demos repo for the bar new demos should meet.