API Reference

API Reference

Base URL is wherever the backend is running, http://localhost:8000 by default. There is no authentication: the backend is meant to run on your own machine, bound to loopback.

{id} is a job id, {faceId} a unique-face id, {imgId} an image id. All are UUIDs.

Jobs

Method	Endpoint	Description
POST	/api/jobs/upload	Upload images or a ZIP, creating a new job
POST	/api/jobs/{id}/add-images	Add more images to an existing job
GET	/api/jobs	List recent jobs, newest first
GET	/api/jobs/{id}	Job status and progress
POST	/api/jobs/{id}/start	Begin processing
POST	/api/jobs/{id}/pause	Pause, or resume if already paused
POST	/api/jobs/{id}/stop	Stop processing
DELETE	/api/jobs/{id}	Delete the job, its records, and its files
GET	/api/jobs/{id}/results	Results for both the list and graph views

Uploads are multipart/form-data with one or more files fields. Both upload endpoints return the job id, the accepted image count, and any rejected filenames. A request over a configured limit returns 413 — see Configuration.

GET /api/jobs/{id} reports status, step, and per-step progress counters. status is one of pending, processing, paused, stopped, completed, failed.

Face management

Method	Endpoint	Description
PATCH	/api/jobs/{id}/faces/{faceId}	Rename a face
POST	/api/jobs/{id}/faces/merge	Group faces together
POST	/api/jobs/{id}/faces/{faceId}/ungroup	Take a face out of its group
POST	/api/jobs/{id}/faces/group/{groupId}/set-primary	Change which face represents a group
POST	/api/jobs/{id}/faces/{faceId}/disable	Toggle whether a face is hidden
DELETE	/api/jobs/{id}/faces/{faceId}	Delete a face and its matches

Merging is not destructive. Faces are grouped, not combined: members keep their own matches, the group can be dissolved, and the display face can be swapped at any time. Deleting a group's primary promotes one of the remaining members rather than orphaning them.

Image and face assignment

Method	Endpoint	Description
POST	/api/jobs/{id}/images/{imgId}/faces/{faceId}	Link a face to a photo, optionally with a bounding box
DELETE	/api/jobs/{id}/images/{imgId}/faces/{faceId}	Unlink a face from a photo

The optional face_box body field is [top, right, bottom, left] in pixels, in the coordinate space of the original image.

Everything else

Method	Endpoint	Description
WS	/ws/{id}	Live processing progress
GET	/thumb/{path}?size=200	Thumbnail, generated on demand and cached on disk
GET	/api/settings	Current crop padding and tolerance
PUT	/api/settings	Update crop padding and tolerance
GET	/health	Returns {"status": "ok"}

size is clamped to between 50 and 400. path is confined to the uploads and results directories; anything resolving outside them returns 404.

/api/settings writes process-wide values, so it affects every session on that backend, not just one.

WebSocket events

Connect to /ws/{id} while a job runs. Each message is a JSON object with a type:

Type	Meaning
progress	step, processed, total, current_file
face_found	A new person was found; carries the id and image URL
match	A photo was linked to a person
notification	An informational, warning, or error message
paused, resumed, stopped	State changes
done	Processing finished
error	Processing failed; carries a message

The socket closes after done, stopped, or error. It only attaches to a job that is currently active; for a finished job, read GET /api/jobs/{id}/results instead.