Gallery HTTP interface
videre gallery starts a small HTTP server on your own machine. The gallery
pages use that server to fetch rows, thumbnails, face data, marks and people
updates while you browse.
The interface is local. It binds to 127.0.0.1, exists only while
videre gallery is running, and reads or writes the database chosen when the
server started. You can call it from your own local tools, but it is not a
hosted service and should not be exposed to other machines.
videre gallery --browsevidere gallery --port 8080The examples below use http://127.0.0.1:7878, the default address. Without
--port a busy 7878 advances to the next free port, so check the startup line
before assuming 7878; an explicit --port is used exactly.
Page routes
Section titled “Page routes”| Route | What it serves |
|---|---|
GET / |
All files |
GET /search |
A search as a page: ?like=<hash> ranks by an example, ?q= words by meaning, and q’s filters narrow either |
GET /duplicates |
Duplicate review |
GET /people |
People and face labeling |
GET /date |
Date drill-down |
GET /date/{year} |
Files for one year |
GET /date/{year}/{month} |
Files for one month |
GET /date/{year}/{month}/{day} |
Files for one day |
GET /people/cluster/{id} |
One face cluster |
GET /people/person/{name} |
One person |
GET /map |
Location cluster map with the full file grid |
GET /map?near={lat},{lon} |
Map centred on the cluster nearest a coordinate pair (used by the lightbox place link) |
GET /map/location/{name} |
One addressable location drill-down |
GET /events |
Automatic travel-trip overview |
GET /events/{key} |
One trip’s media (key is its first photo anchor’s compact time and full hash) |
GET /settings |
Redirects to /settings/config |
GET /settings/{tab} |
The settings pages: config, gallery, or manage (gallery import, export and reset) |
GET /diagnostics |
Redirects to /diagnostics/status |
GET /diagnostics/{tab} |
The Diagnostics pages: status, stats, or logs |
Date route segments are zero-padded where applicable: YYYY, YYYY/MM and
YYYY/MM/DD. Invalid date routes return 404 Not Found.
GET /date also accepts range query parameters:
| Query | Meaning |
|---|---|
from=YYYY[-MM[-DD]] |
Inclusive lower bound |
to=YYYY[-MM[-DD]] |
Exclusive upper bound |
Partial bounds expand to the first day of the period. For example,
from=2025 starts at 2025-01-01, and to=2018 stops before 2018-01-01.
When from is present without to, the range runs through today. Invalid
query dates or empty ranges return 400 Bad Request.
curl "http://127.0.0.1:7878/date/2025/06/03"curl "http://127.0.0.1:7878/date?from=2016-05&to=2017"Map location names use the same normalized, URL-safe identity rule as people.
When more than one cluster has the same normalized name, the route selects the
largest cluster, then the lowest cluster id. The optional positive radius
query is measured in kilometers; without it the route uses the library’s
routes.map.radiusKm setting when it is above 0, and otherwise the cluster’s
stored radius. An unknown name still returns the working map page with HTTP 200 and an
unknown-location state.
GET /map?near={lat},{lon} takes a "lat,lon" pair instead of a name and
resolves it to the cluster whose centroid is nearest by haversine distance,
bootstrapping that cluster’s drill-down. The lightbox place link uses it because
a photo’s reverse-geocoded place name is finer than any cluster name; the client
then rewrites the address bar to the resolved /map/location/{name}. A library
with no clusters resolves to the unselected map.
Settings
Section titled “Settings”The library’s gallery settings, stored in .videre/gallery.json. See
settings for the keys and defaults. Every
response has the same shape:
{ "effective": { "resume": { "route": "/" }, "routes": { "files": { "view": "list", "...": "..." } } }, "overrides": { "routes": { "files": { "view": "list" } } }, "ignored": [], "error": null, "path": "/Users/me/Photos/.videre/gallery.json"}effective is the defaults with overrides (the file’s contents) merged on
top. ignored lists the dotted paths of overrides whose type does not match
the default, which the merge skipped. error explains why the file could not
be read, when it exists but is not a JSON object; the effective settings are
then the defaults.
Write bodies must be a JSON object sent as application/json or
application/merge-patch+json. A write answers 409 Conflict while the file
is unreadable, so hand edits are never overwritten, and 413 Payload Too Large
when the result would exceed 64 KiB.
GET /api/settings
Section titled “GET /api/settings”The current settings, read from disk, so a hand edit shows up without a restart.
PATCH /api/settings
Section titled “PATCH /api/settings”A JSON merge patch (RFC 7396) over
the stored overrides. null removes a key, reverting it to its default. After
every write, PATCH or PUT, any value equal to its default is dropped, so
the file only ever holds what differs. Every incoming value the settings
schema describes is checked first; any refused value answers
422 Unprocessable Entity with {"errors": {"<dotted.path>": "<message>"}}
and nothing is written.
curl -X PATCH -H 'Content-Type: application/merge-patch+json' \ -d '{"routes":{"files":{"tile":{"rowHeight":320}}}}' \ http://127.0.0.1:7878/api/settingsPUT /api/settings
Section titled “PUT /api/settings”Import. The body must hold a routes or a faces object, or both; each one
present replaces that stored section wholesale. Everything else in the file,
including where the library reopens, is kept. {"routes":{},"faces":{}}
resets every preference to its default. Values are checked as for PATCH.
PATCH /api/config
Section titled “PATCH /api/config”Changes videre config keys, named as videre config set names them: {"run-history": 5, "similar-min-score": null}. null
unsets a key. Every value is checked before the config is written once, so a
save lands whole or not at all; a refused one answers 422 with
{"errors": {"<key>": "<message>"}}. The reply holds every key’s value as
values. Turning street-detail off deletes the street map, and
deleted_street_map_bytes says how much.
GET /api/files
Section titled “GET /api/files”Returns a page of file rows. By default it lists all scanned paths.
| Query | Meaning |
|---|---|
view=all |
All database rows. This is the default |
view=date |
One row per hash, ordered for the date view |
offset=<n> |
Page offset. The default is 0 |
limit=<n> |
Page size. The default is 200, capped by the server |
date=YYYY[-MM[-DD]] |
Date prefix used by the date view |
from=YYYY[-MM[-DD]] |
Inclusive date lower bound for view=date |
to=YYYY[-MM[-DD]] |
Exclusive date upper bound for view=date |
hashes=<a,b,c> |
Comma-separated hashes to resolve after a search |
lat=<number> |
Center latitude for a view=all proximity filter |
lon=<number> |
Center longitude for a view=all proximity filter |
radius=<km> |
Positive radius in kilometers for a view=all proximity filter |
cluster=<id> |
Location cluster for a view=all district filter, given with place |
place=<name> |
One place name within cluster; empty means the cluster’s files with no name yet |
sort=<date|name|size|rating|liked|type> |
Field the files are ordered by. Default date. Unknown values fall back to the default |
dir=<asc|desc> |
Sort direction. Default desc. path is always the final tie-break, so pages stay stable |
q=<query> |
A query. Its filters narrow the page and total; its words do not filter |
lat, lon and radius must be supplied together. The server first narrows
GPS-bearing rows with the coordinate index, then applies exact great-circle
distance, so the returned page and total describe the same circle. The date
view ignores all three parameters and keeps its own one-row-per-hash behavior.
cluster and place select one district of a city exactly: the cluster’s
files whose place name is place, the files the map’s district marker counts.
They go together, and not with lat, lon and radius; any other mix answers
400.
Every sort puts nulls last in both directions (undated files, unrated files),
and appends path as the final tie-break, so two consecutive pages never
share a row and “Show more” concatenates into the sorted order.
With q, the response adds library_total, the number of files in the
library, so a client can say “N of M”, and text, the query’s words when it
has any, for the client to rank through /api/search. A query that cannot run
answers 400 {"error": "...", "at": 7}, where at is the zero-based
character offset of a syntax error, or null when there is none to point at.
curl "http://127.0.0.1:7878/api/files?limit=1"curl "http://127.0.0.1:7878/api/files?view=date&from=2025-01-01&to=2026-01-01&limit=100"curl "http://127.0.0.1:7878/api/files?view=all&lat=52.52&lon=13.405&radius=25"{ "total": 42, "offset": 0, "files": [ { "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "path": "/Users/me/Photos/IMG_0001.jpg", "ext": "jpg", "size": 2457600, "cr": "2026-04-12T10:30:00", "mo": "2026-04-12T10:31:00", "ex": "2026-04-12T10:30:00", "lat": 41.0082, "lon": 28.9784, "w": 4032, "h": 3024, "tb": null, "fb": null, "meta": { "faces": [{ "id": 12, "name": "ayse" }], "location": { "lat": 41.0082, "lon": 28.9784 } }, "copies": 1, "rating": 5, "pick": "keep", "label": "red", "liked": true } ]}PATCH /api/files/{hash}
Section titled “PATCH /api/files/{hash}”Updates gallery marks for one hash. Every field is optional. A missing field leaves that mark unchanged.
| Field | Meaning |
|---|---|
rating |
1 through 5, or 0 to clear the rating |
pick |
Pick state such as keep, reject, or none to clear it |
label |
Colour label such as red, or none to clear it |
liked |
Boolean like state |
curl -i -X PATCH \ "http://127.0.0.1:7878/api/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \ -H "content-type: application/json" \ -d '{"rating":5,"pick":"keep","label":"red","liked":true}'HTTP/1.1 200 OKcontent-length: 0GET /api/files/{hash}/raw
Section titled “GET /api/files/{hash}/raw”Serves bytes for one library file. The optional size query asks the gallery
to return a thumbnail-sized rendition when it can. JPEG and other browser-raster
renditions apply embedded EXIF orientation before resizing and encoding. The
gallery adds an opaque preview-version query when needed to keep browser and
server caches in step; local API callers do not need to supply it.
MP4 and MOV responses support one standard Range: bytes=... request and are
streamed from disk. A satisfiable range returns 206 Partial Content with
Accept-Ranges, Content-Range and Content-Length headers. An invalid or
unsatisfiable range returns 416 Range Not Satisfiable. This lets browsers load
video metadata without downloading whole videos or blocking image thumbnails.
curl -i \ "http://127.0.0.1:7878/api/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/raw?size=512"HTTP/1.1 200 OKcontent-type: image/jpegcurl -i \ -H "Range: bytes=0-1023" \ "http://127.0.0.1:7878/api/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/raw"HTTP/1.1 206 Partial Contentaccept-ranges: bytescontent-range: bytes 0-1023/2457600content-length: 1024POST /api/files/{hash}/rotate
Section titled “POST /api/files/{hash}/rotate”Rotates one photo 90 degrees clockwise by bumping its EXIF Orientation tag in
place - no pixels are re-encoded - and drops the file’s cached previews so the
grid and lightbox re-render upright. The photo’s display-canvas face boxes and
landmarks are turned with it, so face crops stay on their faces and keep their
people labels. Supported for EXIF-bearing images (JPEG, PNG, TIFF, WebP),
including one that has no EXIF yet, which gets its first EXIF block; any
other format (video, HEIC, and the like) returns 415 Unsupported Media Type.
The response body carries the new orientation value.
curl -X POST \ "http://127.0.0.1:7878/api/files/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/rotate"{ "orientation": 6 }Selections
Section titled “Selections”The selection bar’s writes. Each takes hashes, 1 to 10,000 content hashes
the library knows; an empty or oversized list answers 400 {"error":"invalid_parameter","field":"hashes"}, and one unknown hash refuses
the whole request with 400 {"error":"unknown_hash"}, so a stale page never
believes it changed something. Marks and tags are per content hash, so every
copy of a photo changes with it.
POST /api/files/marks
Section titled “POST /api/files/marks”The fields of PATCH /api/files/{hash} (rating 0 clears, pick and
label "none" clear, liked), for every hash. pick toggles: asking for
the pick every item already has clears it; the response’s pick says which
was applied. A body with no mark field answers 400 {"error":"no_change"}.
curl -X POST "http://127.0.0.1:7878/api/files/marks" \ -H "content-type: application/json" -d '{"hashes":["aaaa…","bbbb…"],"rating":4,"liked":true}'{ "updated": 2, "pick": null }POST /api/files/tags
Section titled “POST /api/files/tags”Adds add then removes remove on every hash. Tags are trimmed; blank ones
are ignored.
{ "hashes": ["aaaa…"], "add": ["İstanbul"], "remove": ["draft"] }GET /api/tags
Section titled “GET /api/tags”Every tag in the library with how many items carry it, most used first; the selection bar’s tag suggestions.
[{ "tag": "İstanbul", "count": 12 }]POST /api/files/rotate
Section titled “POST /api/files/rotate”A quarter turn (direction cw or ccw) for every hash, as
POST /api/files/{hash}/rotate does for one. Items that cannot carry an
orientation (videos, RAW) are skipped and counted.
{ "rotated": 10, "skipped": 2, "failed": 0 }POST /api/files/delete
Section titled “POST /api/files/delete”Moves every file of each hash (all copies) to the system Trash, where it can
be restored, and removes their rows from the library; marks, tags and faces
stay until videre prune clears data for missing files.
With "dry_run": true it only counts, which the confirmation dialog shows.
{ "hashes": ["aaaa…"], "dry_run": true }{ "items": 1, "files": 2, "photos": 1, "videos": 0, "extra_copies": 1 }The real run adds trashed (hashes with no file left) and failed ([{ path, error }] for files that could not be moved, which keep their rows). It needs
the library to itself: while another videre command or a watch stage is
working, it answers 409 {"error":"library_busy"} and moves nothing.
POST /api/duplicates/trash
Section titled “POST /api/duplicates/trash”Moves the copies of the Duplicates page’s groups to the system Trash, keeping
each group’s first file: the groups, keeper rule and removal of
videre dedupe trash, recorded the same way, so
videre dedupe undo puts them back. kinds are the page’s kinds, q its
query (a group with a matching file, taken whole), and keepers, when given,
picks the groups whose first file is one of these paths (one group’s Trash
copies); without it every group goes (Trash all copies).
{ "kinds": ["exact", "creation"], "q": "date:2015", "keepers": ["/Fotoğraflar/IMG_1.jpg"] }{ "removed": 1, "already_gone": 0, "failed": [] }A review-only kind answers 400 {"error":"review_only_kind"}, a query that
cannot run 400 {"error":"query"}, and a library another command holds 409 {"error":"library_busy"}; nothing is moved.
Dates, search and locations
Section titled “Dates, search and locations”GET /api/dates
Section titled “GET /api/dates”Returns date buckets for the year, month or day drill-down.
| Query | Meaning |
|---|---|
level=year |
Return year buckets. This is the default |
level=month |
Return month buckets under parent=YYYY |
level=day |
Return day buckets under parent=YYYY-MM |
parent=<prefix> |
Parent year or month |
q=<query> |
A query. Only matching files are counted, and a period with none is left out |
With q, the response adds matched and library_total: the date view’s
files (one per content hash) that match, and all of them. A query that cannot
run answers 400 {"error": "...", "at": 7}, as GET /api/files does.
curl "http://127.0.0.1:7878/api/dates?level=month&parent=2026"{ "buckets": [ { "key": "2026-04", "count": 18, "sample": { "path": "/Users/me/Photos/IMG_0001.jpg", "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "ext": "jpg", "w": 4032, "h": 3024 } } ]}GET /api/events
Section titled “GET /api/events”Returns automatic travel trips, newest first. Home is inferred from the place group with the most assignable media. A short trip needs ten distinct files within a rolling three-hour window that may cross midnight, including three dated, located photos. A multi-day trip needs ten files and at least two such photo anchors on each of two dates. Local stops within one 20 km place group can merge. A stop outside that radius starts a separate candidate trip that must qualify independently; a home photo or a gap over 72 hours between destination photo anchors also ends a trip. The ten-file, three-hour and 20 km values are fixed. Videos may join a photo-established trip but never anchor one; GPS-less media join only with supporting capture-time and location evidence. Only full stored capture dates count. Filesystem modification times are not used for Events.
Each kind is trip. key is the first destination photo anchor’s
%Y%m%dT%H%M%S wall-clock time, a hyphen and its full content hash; adding an
edge file cannot rename the trip. title uses the dominant stop’s offline
place name, or falls back to Trip, March 2020. place is the full offline
name or null. The empty_reason field is null when trips are present; for
an empty list it is one of no_media, no_capture_dates,
insufficient_location_evidence or no_qualifying_trips. No prior
videre locations or videre embed run is needed. Local outings, manual
membership edits and combining events are not supported.
curl "http://127.0.0.1:7878/api/events"{ "events": [ { "key": "20200312T100000-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "kind": "trip", "title": "Budapest, March 2020 Trip", "start": "2020-03-12 10:00:00", "end": "2020-03-15 16:30:00", "count": 83, "place": "Budapest, HU", "sample": { "path": "/Users/me/Photos/IMG_0001.jpg", "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "ext": "jpg", "w": 4032, "h": 3024 } } ], "empty_reason": null}q=<query> takes a query. Trips are still found
over the whole library, so a query never splits or merges one: it keeps the
trips with a matching member, count counts those members, and sample is
one of them. None matching is "empty_reason": "no_matching_events". The
response then adds matched and library_total, as GET /api/dates does, and
a query that cannot run answers 400.
GET /api/events/{key}/files
Section titled “GET /api/events/{key}/files”Returns the files of one trip, by its exact members, in the same
{total, offset, files} shape as GET /api/files. key comes from /api/events:
the first destination photo anchor’s compact time, a hyphen, and its full
content hash, so two trips starting in the same second stay distinct. An
unknown or stale key (the library or
the thresholds changed since it was read) returns 404. With q=<query>, only
the members that match.
curl "http://127.0.0.1:7878/api/events/20200312T100000-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/files"GET /api/query/suggest
Section titled “GET /api/query/suggest”What can complete the term at the cursor of a query:
keys while one is typed, the library’s values after key:, and OR, -
and ( after a complete term. The shell completer answers from the same
function, so both offer the same things.
| Query | Meaning |
|---|---|
q=<query> |
The query as typed so far |
cursor=<n> |
Character offset of the cursor. The default is the end of q |
limit=<n> |
Most suggestions returned. The default is 20, capped at 100 |
start is the character offset where the term begins: a client replaces
q from start to cursor with an item’s insert. A value with a space is
inserted quoted. A person is inserted by identity, with the display name as
label and a face_id whose crop /api/faces/{id}/image serves. Values
match folded for case and accents, on the start of any word, so gündo
finds Erhan Gündoğan. Inside a quoted phrase there is nothing to suggest.
curl "http://127.0.0.1:7878/api/query/suggest?q=-person:g%C3%BCndo"{ "start": 1, "items": [ { "insert": "person:erhan_gundogan", "label": "Erhan Gündoğan", "kind": "value", "count": 214, "face_id": 88 } ]}GET /api/search
Section titled “GET /api/search”Ranks photos by text or by similarity to an existing hash: q with words, or
like. With like, q may still carry a query’s
filters, which narrow what is ranked; words with an example, or a query that
cannot run, answer 400.
A text query’s score is the match probability from 0 to 1; results below
the library’s search_min_match are left out when one is set (none by
default). A like search’s score is the
similarity, from -1 to 1, kept above similar_min_score when that is set. See
search.
| Query | Meaning |
|---|---|
q=<text> |
Text query |
like=<hash> |
Find media similar to an existing hash |
limit=<n> |
Result count. The default is 24, at most 200 |
offset=<n> |
Where this page starts in the ranking; 0 when absent |
more says whether a page after this one exists. A ranked search’s total
counts only what was ranked for this page, so it does not answer that.
curl "http://127.0.0.1:7878/api/search?q=red%20kite&limit=2"{ "total": 2, "more": false, "results": [ { "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "score": 0.97 }, { "hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "score": 0.91 } ]}GET /api/locations
Section titled “GET /api/locations”Resolves one coordinate pair to a place name and caches the answer in the database.
curl "http://127.0.0.1:7878/api/locations?lat=41.0082&lon=28.9784"{ "name": "Istanbul, Turkey"}When the location cannot be resolved, name is null.
{ "name": null}GET /api/location-clusters
Section titled “GET /api/location-clusters”Returns the clusters produced by videre locations, largest first. The
continent field is derived locally from each centroid and is used by the Map
view’s world overview. A library that has not run videre locations returns an
empty array.
With q=<query>, a query, only the clusters holding
a matching file are returned, photo_count counts those files, and the order is
by that count. A query that cannot run answers 400.
curl "http://127.0.0.1:7878/api/location-clusters"[ { "cluster_id": 7, "name": "Berlin, Germany", "route_name": "berlin_germany", "centroid_lat": 52.52, "centroid_lon": 13.405, "photo_count": 42, "radius_km": 15.0, "continent": "Europe" }]route_name is the normalized addressable identity used under
/map/location/{name}.
GET /api/location-clusters/{id}/points
Section titled “GET /api/location-clusters/{id}/points”Every file of one cluster with GPS, as [lat, lon, place], for the Map view to
split a city into districts and street groups when you zoom in. place indexes
places, the per-file place names videre locations
writes; -1 is a file with no name yet. Coordinates are rounded to 5 decimals
(about a metre). q=<query> keeps the matching files only, a query that cannot
run answers 400, and an unknown cluster 404.
curl "http://127.0.0.1:7878/api/location-clusters/7/points"{ "places": ["Mitte, DE", "Kreuzberg, DE"], "points": [[52.52001, 13.40499, 0], [52.499, 13.403, 1], [52.51, 13.39, -1]]}Street detail
Section titled “Street detail”On by default; turned off per library (videre config set street-detail false; see
the gallery’s map). Off, the status is
{"enabled":false,"state":"off"}, any street map left on disk is deleted, the
two POST endpoints answer 403 and the tiles 404.
GET /api/basemap/detail
Section titled “GET /api/basemap/detail”{"enabled":true,"state":"ready","bytes":412345678,"cells":31,"done":0,"total":0,"error":null}state is absent, downloading (with done and total tile bytes),
ready, stale (the library has places outside the downloaded cells) or
failed (with error). cells counts the 1-degree cells the library’s places
touch.
POST /api/basemap/detail/plan
Section titled “POST /api/basemap/detail/plan”Reads the source’s directories for the cells and answers
{"cells":31,"bytes":412345678}, the download’s size. This already tells the
host which cells are wanted, so the map calls it only after a click. A host
failure answers 502.
POST /api/basemap/detail/ensure
Section titled “POST /api/basemap/detail/ensure”Starts the download in the background (the glyphs, then the tiles) and answers
the status at once; the map polls GET /api/basemap/detail.
GET /tiles/detail.pmtiles
Section titled “GET /tiles/detail.pmtiles”The library’s street map, with Range support, read by MapLibre through the
pmtiles protocol. 404 when absent or off.
GET /fonts/{stack}/{range}
Section titled “GET /fonts/{stack}/{range}”Glyphs for street and place names, Noto Sans Regular in its Latin ranges,
from the machine’s shared cache. Any other stack or range is 404.
Map basemap
Section titled “Map basemap”The Map view renders MapLibre GL JS over an offline vector basemap: a PMTiles archive downloaded once per machine into the shared geo cache on first use. View time is fully offline; these three endpoints drive the one-time acquisition and the local, Range-capable serving of the archive.
GET /tiles/basemap.pmtiles
Section titled “GET /tiles/basemap.pmtiles”Serves the basemap archive with HTTP Range support (Accept-Ranges: bytes),
which is how the PMTiles protocol reads byte ranges out of the file. Returns
404 when the archive is absent (the client then POSTs to
/api/basemap/ensure), 409 with the status body while a download is in
flight (the client keeps polling), and 200/206 once the archive is ready.
GET /api/basemap/status
Section titled “GET /api/basemap/status”Reports the archive’s download state, which the page polls after starting a download.
curl "http://127.0.0.1:7878/api/basemap/status"{ "state": "ready", "bytes": 41943040 }state is absent, partial (a download is in progress), or ready.
POST /api/basemap/ensure
Section titled “POST /api/basemap/ensure”Starts the once-per-machine download if the archive is absent and none is already running, then returns the current status immediately (same body shape as the status endpoint). Repeated calls while a download runs are no-ops.
GET /api/processing
Section titled “GET /api/processing”While videre watch runs on the library, each of its
stages that still has files to process, which the nav polls to show its
“still processing” note. watch is false and stages empty when no watcher
runs. Embed and classify appear only once their model is downloaded, since
watch never fetches it.
curl "http://127.0.0.1:7878/api/processing"{ "watch": true, "stages": [{ "stage": "faces", "outstanding": 12 }] }GET /api/diagnostics/status
Section titled “GET /api/diagnostics/status”The document videre status --json prints, for the
Diagnostics page: coverage, pipeline runs with their history, watch liveness,
the latest run of each command as its log records it, and date sources.
GET /api/diagnostics/stats
Section titled “GET /api/diagnostics/stats”The document videre stats --json prints, with the first
ten mismatched files.
GET /api/diagnostics/logs
Section titled “GET /api/diagnostics/logs”One page of the library’s log lines, newest first, across commands and rotated files. Query parameters, all optional:
| Parameter | Meaning |
|---|---|
command |
Only this command’s logs |
level |
error, warn (default: warnings and errors) or info, which reads the trace files and needs log-level info |
since |
Only lines at or after this RFC 3339 time |
q |
Only lines whose message or path contains this, ignoring case and diacritics (cicek finds ÇİÇEK) |
before |
Only lines before this RFC 3339 time: the last line’s ts, for the next page |
A bad level or time is 400.
curl "http://127.0.0.1:7878/api/diagnostics/logs?command=faces&level=error"{ "lines": [{ "ts": "2026-10-09T15:50:01.2Z", "level": "warn", "command": "faces", "run": "…", "stage": null, "kind": "source_unavailable", "path": "/Photos/IMG_4411.HEIC", "message": "…" }], "more": false, "unreadable": 0, "commands": ["faces", "gallery", "scan"], "no_trace": []}no_trace names the commands that have no trace file when level=info asked
for one. Pages hold 200 lines, more only to keep lines of one instant together.
GET /vendor/{version}/{asset}
Section titled “GET /vendor/{version}/{asset}”Serves the vendored map libraries compiled into the binary, with a long-lived
immutable cache: maplibre-gl.js, maplibre-gl.css, and pmtiles.js. Loaded
only by the Map page, so the ~1 MB of script never weighs on the other gallery
views. The {version} segment is videre’s own version, emitted by the page as a
cache buster so an upgrade fetches fresh bytes on the same port; its value is not
validated. Any other {asset} is 404.
GET /favicon.svg, GET /favicon.ico
Section titled “GET /favicon.svg, GET /favicon.ico”The videre mark as SVG, cached for a day. Every page links /favicon.svg;
/favicon.ico answers with the same bytes for browsers that ask for it anyway.
People
Section titled “People”GET /api/people
Section titled “GET /api/people”Searches known people by their stored label or display name. Use the name
query to filter.
curl "http://127.0.0.1:7878/api/people?name=ay"["ayse", "ayse_yilmaz"]POST /api/people
Section titled “POST /api/people”Creates a person from one or more face ids.
curl -i -X POST "http://127.0.0.1:7878/api/people" \ -H "content-type: application/json" \ -d '{"name":"Ayse Yilmaz","face_ids":[12,13]}'HTTP/1.1 200 OKcontent-length: 0GET /api/people/{name}
Section titled “GET /api/people/{name}”Returns the display name and one page of the assigned faces for one
person, the primary face first. limit=<n> (default 200, at most 1000)
and after=<id> (the previous page’s next) page them; face_total counts
them all and next is null at the end.
curl "http://127.0.0.1:7878/api/people/ayse_yilmaz"{ "label": "ayse_yilmaz", "full_name": "Ayse Yilmaz", "faces": [ { "face_id": 12, "hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "path": "/Users/me/Photos/IMG_0001.jpg", "is_primary": true } ], "face_total": 1, "next": null}PATCH /api/people/{name}
Section titled “PATCH /api/people/{name}”Updates the display name for an existing person.
curl -i -X PATCH "http://127.0.0.1:7878/api/people/ayse_yilmaz" \ -H "content-type: application/json" \ -d '{"full_name":"Ayse Demir"}'HTTP/1.1 200 OKcontent-length: 0DELETE /api/people/{name}
Section titled “DELETE /api/people/{name}”Unassigns a person from their faces.
curl -i -X DELETE "http://127.0.0.1:7878/api/people/ayse_yilmaz"HTTP/1.1 200 OKcontent-length: 0PUT /api/people/{name}/faces
Section titled “PUT /api/people/{name}/faces”Names faces as a person, creating the person when the name is new. The faces must be unnamed, and several faces must be one cluster’s whole unassigned group; anything else is refused with the reason.
curl -i -X PUT "http://127.0.0.1:7878/api/people/ayse_yilmaz/faces" \ -H "content-type: application/json" \ -d '{"face_ids":[12,13,14]}'HTTP/1.1 200 OKcontent-length: 0Recluster
Section titled “Recluster”The People toolbar’s recluster. Parameters are the eight clustering values of
videre faces, by their flag names
with underscores: eps, min_cluster_size, merge_sim, min_face_size,
max_generic_sim, max_landmark_error, min_blur, attach_sim. A request
sends any of them; the rest come from the library’s saved settings, then the
built-in values. Only unlabeled faces are regrouped; named faces never move.
GET /api/faces/cluster-params
Section titled “GET /api/faces/cluster-params”The parameters a recluster would use now, what the library has saved, the built-in values, and any problem reading the saved ones.
curl "http://127.0.0.1:7878/api/faces/cluster-params"{ "effective": { "eps": 0.7, "min_cluster_size": 3, "merge_sim": 0.35, "min_face_size": 80.0, "max_generic_sim": 0.4, "max_landmark_error": 7.0, "min_blur": 80.0, "attach_sim": 0.4 }, "saved": { "eps": 0.7 }, "defaults": { "eps": 0.6, "min_cluster_size": 3, "merge_sim": 0.35, "min_face_size": 80.0, "max_generic_sim": 0.4, "max_landmark_error": 7.0, "min_blur": 80.0, "attach_sim": 0.4 }, "warnings": []}POST /api/faces/recluster/preview
Section titled “POST /api/faces/recluster/preview”Computes the grouping these parameters would produce and writes nothing.
curl -X POST "http://127.0.0.1:7878/api/faces/recluster/preview" \ -H "content-type: application/json" -d '{"eps":0.7,"min_cluster_size":2}'{ "params": { "eps": 0.7, "min_cluster_size": 2, "...": "..." }, "total_faces": 560, "clustered_faces": 310, "cluster_count": 42, "singletons": 250, "held_out": 61, "before": { "cluster_count": 0, "singletons": 560 }}singletons counts every unlabeled face left ungrouped, held_out the part
of them the quality gates kept out of clustering. before is the current
state. A value out of range answers 400 naming it:
{"error":"invalid_parameter","field":"eps"}.
POST /api/faces/recluster
Section titled “POST /api/faces/recluster”Applies the same pass: regroups the unlabeled faces, records a
face-recluster run (shown by videre status), saves
the parameters that differ from the built-in values to .videre/gallery.json
under faces.clustering (removing the entry when none differ). From then on videre faces and videre watch cluster this library with those values unless a flag says otherwise.
The response is the preview’s, plus "saved": true, or "saved": false
with settings_error when gallery.json could not be read; the grouping is
applied either way and the unreadable file is left untouched. While a videre faces or videre watch run holds the library’s faces lock, it answers 409 {"error":"faces_busy"} and changes nothing.
Faces and clusters
Section titled “Faces and clusters”GET /api/faces
Section titled “GET /api/faces”Returns the face labeling state grouped into named people, clusters and
singletons. With q=<query>, a query, only those
with a face in a matching file, each whole, plus matched and library_total
as GET /api/dates gives them; a query that cannot run answers 400.
People and clusters always come whole. Singletons come a page at a time, in face id order:
| Query | Meaning |
|---|---|
singles_limit=<n> |
Singletons in this page. The default is 200, at most 1000; 0 returns none |
singles_after=<id> |
Start after this face id; singles_next from the previous page |
singles_total counts every singleton the query keeps, and singles_next is
the id to page after, or null at the end. Paging by id keeps a page in place
when faces before it are named.
curl "http://127.0.0.1:7878/api/faces"{ "people": [ { "label": "ayse_yilmaz", "full_name": "Ayse Yilmaz", "face_ids": [12, 13], "representative_id": 12, "hashes": [ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ] } ], "clusters": [ { "cluster_id": 7, "face_ids": [21, 22], "hashes": [ "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" ] } ], "singletons": [ { "face_id": 31, "hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc" } ], "singles_total": 1, "singles_next": null}PATCH /api/faces/{id}
Section titled “PATCH /api/faces/{id}”Marks one face as the primary face for a person.
curl -i -X PATCH "http://127.0.0.1:7878/api/faces/12" \ -H "content-type: application/json" \ -d '{"person_label":"ayse_yilmaz"}'HTTP/1.1 200 OKcontent-length: 0DELETE /api/faces/{id}
Section titled “DELETE /api/faces/{id}”Unassigns one face.
curl -i -X DELETE "http://127.0.0.1:7878/api/faces/12"HTTP/1.1 200 OKcontent-length: 0GET /api/faces/{id}/image
Section titled “GET /api/faces/{id}/image”Serves the cropped face thumbnail as JPEG bytes.
curl -i "http://127.0.0.1:7878/api/faces/12/image"HTTP/1.1 200 OKcontent-type: image/jpegGET /api/faces/{id}/original
Section titled “GET /api/faces/{id}/original”Serves the original source file for a face, with a content type inferred from the file.
curl -i "http://127.0.0.1:7878/api/faces/12/original"HTTP/1.1 200 OKcontent-type: image/jpegGET /api/clusters/{id}
Section titled “GET /api/clusters/{id}”Returns one face cluster.
curl "http://127.0.0.1:7878/api/clusters/7"{ "cluster_id": 7, "faces": [ { "face_id": 21, "hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "path": "/Users/me/Photos/IMG_0021.jpg" } ]}DELETE /api/clusters/{id}
Section titled “DELETE /api/clusters/{id}”Dissolves one cluster.
curl -i -X DELETE "http://127.0.0.1:7878/api/clusters/7"HTTP/1.1 200 OKcontent-length: 0Server Control
Section titled “Server Control”POST /api/quit
Section titled “POST /api/quit”Stops the running gallery server.
curl -i -X POST "http://127.0.0.1:7878/api/quit"HTTP/1.1 200 OKcontent-length: 0Endpoint Index
Section titled “Endpoint Index”| Endpoint | Purpose |
|---|---|
GET /api/files |
List files or fetch files by hash |
PATCH /api/files/{hash} |
Update marks on one file |
GET /api/files/{hash}/raw |
Serve bytes for one library file |
POST /api/files/{hash}/rotate |
Rotate one photo 90 degrees clockwise (EXIF) |
POST /api/files/marks |
Set marks on a selection |
POST /api/files/tags |
Add or remove tags on a selection |
GET /api/tags |
List the library’s tags with counts |
POST /api/files/rotate |
Rotate a selection a quarter turn |
POST /api/files/delete |
Move a selection’s files to the system Trash |
POST /api/duplicates/trash |
Move the Duplicates page’s copies to the system Trash |
GET /api/dates |
Read date buckets |
GET /api/events |
List automatic travel trips and an empty reason when none qualify |
GET /api/events/{key}/files |
Exact files of one trip |
GET /api/search |
Rank by text or by an existing file hash |
GET /api/query/suggest |
Complete the query term at the cursor |
GET /api/locations |
Resolve one coordinate pair to a place name |
GET /api/location-clusters |
List location clusters for the Map view |
GET /api/location-clusters/{id}/points |
One cluster’s files as points, for districts and streets |
GET /tiles/basemap.pmtiles |
Serve the offline basemap archive (Range) |
GET /api/basemap/status |
Report the basemap download state |
POST /api/basemap/ensure |
Start the one-time basemap download |
GET /api/basemap/detail |
Report the street map: off, absent, downloading, ready, stale or failed |
POST /api/basemap/detail/plan |
Size the street-map download for this library’s places |
POST /api/basemap/detail/ensure |
Start the street-map download |
GET /tiles/detail.pmtiles |
Serve the library’s street map (Range) |
GET /fonts/{stack}/{range} |
Serve the glyphs street and place names are drawn with |
GET /api/processing |
Stages watch still has files to process |
GET /api/diagnostics/status |
What videre status --json prints |
GET /api/diagnostics/stats |
What videre stats --json prints |
GET /api/diagnostics/logs |
Read the log lines, filtered and paged |
GET /vendor/{version}/{asset} |
Serve a vendored map library (MapLibre, pmtiles) |
GET /favicon.svg |
Serve the videre icon |
GET /favicon.ico |
Serve the videre icon, for browsers that ask for it |
GET /api/people |
Search people |
POST /api/people |
Create a person from faces |
GET /api/people/{name} |
Read one person |
PATCH /api/people/{name} |
Update one person’s display name |
DELETE /api/people/{name} |
Unassign one person |
PUT /api/people/{name}/faces |
Attach faces to a person |
GET /api/faces |
Read people, clusters and singletons |
PATCH /api/faces/{id} |
Mark a face as primary for a person |
DELETE /api/faces/{id} |
Unassign one face |
GET /api/faces/{id}/image |
Serve one face thumbnail |
GET /api/faces/{id}/original |
Serve the source file for one face |
GET /api/clusters/{id} |
Read one cluster |
DELETE /api/clusters/{id} |
Dissolve one cluster |
POST /api/quit |
Stop the gallery server |