Skip to main content

Review

Source: app/api/review.py

Annotations​

GET /api/v1/jobs/{job_id}/annotations​

Paginated list of annotations for a labeling job. Query params: offset, limit, frame_id, class_name.

PATCH /api/v1/annotations/{annotation_id}​

Update an annotation's bbox, class, or accepted state.

POST /api/v1/annotations/merge-classes​

Bulk-rename one class to another across a job (e.g. merge truck and lorry).

Source video inspection​

GET /api/v1/jobs/{job_id}/sources​

List the distinct sources linked to saved annotations in this job. Each entry contains id, filename, duration_s and has_source_video. The list does not include playback URLs. Image-only sources remain listed but have no video.

GET /api/v1/jobs/{job_id}/sources/{video_id}/playback​

Return video_id and a fresh signed url for that source. The caller must have access to both the job and video, and a saved annotation must link them. An unrelated or inaccessible source returns 404, including a clip in the same workspace that has no saved finding in this job. Image-only sources return 404. The signed download supports byte ranges for browser seeking.

Use the saved annotation's source ID and time to navigate. source_pts times are relative to container start. Known FPS-derived times are approximate. Unknown or invalid timing does not support an automatic seek. This endpoint does not run inference, change a review, or establish continuous coverage.

Job management​

PATCH /api/v1/jobs/{job_id}​

Update job metadata (name, description).

DELETE /api/v1/jobs/{job_id}​

Delete a job and all its annotations.

POST /api/v1/jobs/{job_id}/duplicate​

Clone a job — useful when you want to re-run with different prompts but keep the original.

POST /api/v1/jobs/{job_id}/add-class​

Add a new class to a finished job and re-run SAM 3 just for that class.

Classes​

GET /api/v1/jobs/{job_id}/classes​

List all classes present in a job's annotations.

DELETE /api/v1/jobs/{job_id}/classes/{class_name}​

Remove a class entirely (deletes all annotations of that class).

Stats & export​

GET /api/v1/jobs/{job_id}/overview​

High-level summary: frame count, annotation count per class, completion %.

GET /api/v1/jobs/{job_id}/stats​

Detailed stats — distributions, confidence histograms, per-class precision when ground truth is available.

POST /api/v1/jobs/{job_id}/export​

Export the saved annotations to an immutable ZIP in MinIO. The request is {"format": "segment"}; supported formats are segment, detect, obb, classify, and pose. The response includes the format and a download URL.

Pending and accepted annotations are included; rejected annotations are omitted. Export does not certify that a person accepted every label. Rejected-only frames are excluded, since a rejected detection does not establish an empty scene. Source videos stay in separate train/validation groups. One source video cannot provide independent held-out validation, and training rejects that case.

Classification produces rectangular crops from each saved polygon envelope with five pixels of padding, clipped to the source image. Files use train/<class>/*.jpg and val/<class>/*.jpg. Class names must be safe single folder names. Pose produces one polygon-centroid keypoint per object with kpt_shape: [1, 3]. Its box uses the saved valid bbox, or polygon bounds when the bbox is absent. This is a centroid target, not a skeleton or a manually marked anatomical landmark. There is no keypoint editor.

Both formats require finite, nondegenerate normalized polygons. Missing or invalid geometry stops the export; the service does not silently omit an object or substitute a box center for its centroid. The crop and centroid derive from the saved polygon, which can differ from the original mask and retains only its largest contour. The export manifest records source annotation identities and the geometry method.

Only an export matching the job's task updates its current training artifact. Later annotation edits invalidate that pointer. Existing training runs keep their immutable input snapshot. Export again after review changes. If evidence changes while a matching export is being built, publication returns HTTP 409 instead of marking the older ZIP as current. Export again after the edit completes.