GET /healthGET /health/readyGET /api/config
GET /health is a lightweight liveness check. GET /health/ready also checks
database connectivity and returns checks.database=ok or HTTP 503 with
checks.database=error.
Full Stage 7CD adds minimal local identity and permission behavior. This is not production IAM.
Headers:
X-SmartTraffic-ActorX-SmartTraffic-Role
Roles are viewer, operator, reviewer, and admin. Missing headers default
to actor=system and role=operator for local compatibility.
SMARTTRAFFIC_AUTH_MODE=permissive records actor context without blocking
requests. SMARTTRAFFIC_AUTH_MODE=strict enforces the preview permission guard:
viewer: read-only.operator: realtime start / stop, alert actions, and local config writes.reviewer: review actions and Bad Case actions.admin: all preview permissions.
Error responses include error_code, message, detail, and request_id.
Obvious secret / RTSP / password content is redacted from error messages.
POST /api/videos/uploadGET /api/videosGET /api/videos/{video_id}GET /api/videos/{video_id}/framesPOST /api/videos/{video_id}/processGET /api/videos/{video_id}/status
Full Stage 2AB makes the video API DB-backed for video metadata and processing
task lifecycle state. Full Stage 2CD persists core result rows for successful
processing runs. Upload still stores the source video on local disk, while the
videos row stores filename, storage path, status, fps, dimensions, frame
count, duration, camera id, and metadata. GET /api/videos/{video_id}/frames
returns rows from the frames table; Stage 2CD does not auto-extract frame
images.
v1.0.3-final-hardening validates upload extension, size, duration, and codec
before creating the DB video row. Supported extensions remain .mp4, .avi,
.mov, .mkv, and .webm. Default local limits are
SMARTTRAFFIC_MAX_UPLOAD_MB=200,
SMARTTRAFFIC_MAX_VIDEO_DURATION_SECONDS=600, and
SMARTTRAFFIC_ALLOWED_VIDEO_CODECS=avc1,h264,mp4v,xvid,mjpg. Unsupported
extension, empty upload, unreadable metadata, unsupported codec, or excessive
duration return a clear client error; oversized uploads return 413. OpenCV
FOURCC / codec detection can vary by platform and container, so unsupported or
undetectable codec errors are validation boundaries rather than production
transcoding guarantees. Error responses do not expose tracebacks or local
absolute paths.
The frames API is a frame metadata / query contract for DB-backed local
validation. It is not a guarantee that the processing pipeline persists every
decoded frame image by default.
POST /api/videos/{video_id}/process supports:
mode=detection_onlymode=detection_trackingmode=detection_tracking_trajectorydetector_dry_runtracker_dry_runframe_stridemax_framesconf_thresholdiou_thresholdwrite_previewdirection_windowdwell_speed_thresholdmax_history_pointsevent_rules: optional list of EventEngine rule dictionaries.zones: optional list of zone dictionaries.run_events: optional boolean, default true.generate_alerts: optional boolean, default true.record_not_matched: optional boolean, default false.
Stage four trajectory request example:
{
"mode": "detection_tracking_trajectory",
"detector_dry_run": true,
"tracker_dry_run": true,
"frame_stride": 1,
"max_frames": 5,
"direction_window": 2,
"dwell_speed_threshold": 1.0,
"max_history_points": null,
"event_rules": [],
"zones": [],
"run_events": true,
"generate_alerts": true
}Stage four response fields include:
stage = stage_4_trajectory_enginenext_stage = stage_5_event_engine_not_startedtotal_trajectory_pointstrajectory_track_state_countsavg_track_lengthmax_track_lengthavg_speed_px_per_second
avg_speed_px_per_second is a pixel-level speed estimate derived from timestamp or fps. It is not real-world speed in m/s or km/h.
For mode=detection_tracking_trajectory, the process API now runs EventService
after trajectory artifacts are written, writes Stage 6C traffic statistics
artifacts after event artifacts, then runs AlertService. If event_rules /
zones are omitted, the process still writes stable empty event, statistics,
and alert artifacts. The process response keeps the existing summary shape; full
event, statistics, and alert details are queried from analysis-runs endpoints.
Each process request creates a DB processing_tasks row with pending,
running, completed, or failed status, progress, start/finish timestamps,
error message, parameters, and result summary. Each successful process request
also creates a traffic_analysis_runs row, so one video may have multiple
run_id values. Full Stage 2CD imports generated detections.csv,
tracks.csv, trajectory_points.csv, flow_counts.json, and
zone_statistics.json into DB tables while keeping the artifacts. Full Stage
3AB records the current zone/rule config snapshot in the run summary when the
processing flow creates a DB run. v1.0.1-audit-polish also records detector
and tracker business writes in model_runs for DB-backed processing flows,
including sanitized detector model path / dry-run parameters, tracker
parameters, summary metrics, and artifact references.
Manual alignment note:
- Stage 5 is implemented as an artifact-based / in-memory MVP.
- Event and alert artifacts remain available for legacy run directories.
- Detection, tracking, trajectory, flow count, and zone statistic reads are DB-first with artifact fallback.
v1.0.2-spec-alignmentmakesGET /api/analysis-runs/{run_id}/alertsDB-first with artifact fallback, matching the rest of the run-scoped Traffic Analysis Center result reads.- Full Stage 3AB makes Zone / Event Rule CRUD and top-level Event APIs DB-backed.
- Full Stage 3CD makes EventEvidence / RuleExecution lifecycle, Alert Center status transitions, and Review audit trail DB-first with artifact fallback.
- Full Stage 3EF makes Bad Case / Evaluation workflows DB-first with artifact
fallback, including failed cases persisted in
evaluation_results.summary["failed_cases"].
Full Stage 3AB makes these configuration APIs DB-backed. Responses preserve the
existing shape and include version; the DB model stores polygon, direction,
counting-line, target-class, parameter, cooldown, severity, and version data in
the existing structured JSON fields. Full Stage 5AB connects the frontend
ZoneEditor to these APIs so users can draw polygon, direction line, and counting
line geometry, then save and read back DB-backed zones and event rules.
Full Stage 5CD consumes the same zone records in Analysis Detail overlay mode:
polygons, direction lines, counting lines, enabled state, and selected event
zone highlighting are rendered as frontend SVG overlays. Detection, tracking,
trajectory, and event overlays use the existing Analysis Runs read APIs.
Zones:
POST /api/zonesGET /api/zones?video_id=&enabled=GET /api/zones/{zone_id}PATCH /api/zones/{zone_id}DELETE /api/zones/{zone_id}
Event Rules:
POST /api/event-rulesGET /api/event-rules?event_type=&enabled=&zone_id=GET /api/event-rules/{rule_id}PATCH /api/event-rules/{rule_id}DELETE /api/event-rules/{rule_id}
Supported event_type values:
wrong_way_drivingillegal_parkingdanger_zone_intrusionpedestrian_in_vehicle_lanecongestionflow_counting
Event rule severity values are limited to low, medium, and high, matching
the EventEngine contract. POST /api/event-rules and
PATCH /api/event-rules/{rule_id} enforce this in the backend schema; sending
critical as an Event Rule severity is rejected by request validation. Alert
levels are separate generated alert states and may still use info, warning,
and critical.
These endpoints form the Traffic Analysis Center result API surface. Full Stage 2CD makes the run index and core result reads DB-first while preserving artifact fallback. Full Stage 3CD adds DB-first Event / Alert / Review lifecycle reads and writes. Full Stage 3EF adds DB-first Bad Case and Evaluation workflows while preserving artifact fallback.
GET /api/analysis-runsGET /api/analysis-runs/{run_id}GET /api/analysis-runs/{run_id}/manifestGET /api/analysis-runs/{run_id}/detections?limit=100GET /api/analysis-runs/{run_id}/tracks?limit=100GET /api/analysis-runs/{run_id}/trajectory-points?limit=100GET /api/analysis-runs/{run_id}/events?limit=100GET /api/analysis-runs/{run_id}/flow-countsGET /api/analysis-runs/{run_id}/zone-statisticsPOST /api/analysis-runs/{run_id}/alerts/generateGET /api/analysis-runs/{run_id}/alerts?limit=100GET /api/alertsGET /api/alerts/{alert_id}PATCH /api/alerts/{alert_id}/acknowledgePATCH /api/alerts/{alert_id}/resolvePATCH /api/alerts/{alert_id}/ignore
GET /api/processing/tasks
This endpoint exposes the local processing task registry / DB-backed task records used by video processing, rule-rerun requests, and realtime preview start records. Processing task rows include status, mode, progress, timestamps, error message, parameters, result summary, and related video / run ids where available. It is DB-backed for Full Stage 2AB+ flows and is used for local operational visibility, not as a production queue monitor.
v1.0.1-audit-polish makes this endpoint DB-first instead of reading only the
legacy in-memory registry. Supported filters are:
video_idrun_idstatusmodetask_type(matches explicit task type values such asrealtime_processand processing modes such asdetection_only)include_memory(optional debug compatibility flag, default false, merges legacy in-memory tasks after DB rows)
Responses include id, video_id, run_id, task_type, mode, status,
progress, error_message, started_at, finished_at, created_at,
params_json, and result.
GET /api/detectionsGET /api/tracks?run_id=&video_id=&track_id=&limit=100GET /api/trajectories?run_id=&video_id=&track_id=&limit=100
The run-scoped, DB-first / artifact-fallback Analysis Runs endpoints remain the primary result reads:
GET /api/analysis-runs/{run_id}/detectionsGET /api/analysis-runs/{run_id}/tracksGET /api/analysis-runs/{run_id}/trajectory-points
Standalone /api/tracks and /api/trajectories provide DB-backed local lookup
by run_id, video_id, track_id, and limit. Standalone /api/detections
is still a contract-only module boundary; use the run-scoped detections endpoint
for real result reads.
The standalone result endpoints do not replace the run-scoped result APIs and are not production aggregate search endpoints.
tracks rows in the current local prototype are run-level track records plus
metadata / artifact-compatible rows imported from processing output. They are
not a production normalized per-frame tracking table; detailed per-frame
tracking evidence remains represented through Analysis Runs payloads and local
artifacts where available.
Full Stage 6AB/6CD adds a DB-first / artifact-compatible Report Center API for CSV, JSON, PDF, bundle metadata, keyframe summary, and annotated-video reference export. It aggregates existing analysis, event, alert, flow, zone, bad case, and evaluation records. Reports are for analysis and review only; they are not traffic-enforcement artifacts.
GET /api/reports/runsGET /api/reports/{run_id}/summaryGET /api/reports/{run_id}/bundleGET /api/reports/{run_id}/export.jsonGET /api/reports/{run_id}/export.csv?section=eventsGET /api/reports/{run_id}/export.pdf
Supported CSV section values:
eventsalertsflow_countszone_statisticsbad_casesevaluation_results
GET /api/reports/{run_id}/summary returns the selected run summary, section
counts, event / alert / bad-case breakdowns, flow totals, evaluation metric
summary, bundle metadata, keyframe summary, annotated video reference,
available export sections, and the non-enforcement note.
GET /api/reports/{run_id}/export.json returns a structured JSON report:
{
"metadata": {
"schema_version": "full_stage_6ab.report.v1",
"note": "SmartTraffic reports are for analysis and review only; not for traffic enforcement.",
"available_exports": ["events", "alerts"]
},
"run": {},
"events": [],
"alerts": [],
"flow_counts": [],
"zone_statistics": [],
"bad_cases": [],
"evaluation_results": []
}CSV exports always include a stable header row, even when the selected section has no rows. Local absolute paths are sanitized before report payloads are returned.
GET /api/reports/{run_id}/export.pdf returns a lightweight text PDF with run
metadata, event / alert / flow / zone / bad case / evaluation summaries,
available artifact references, and explicit non-enforcement disclaimers. The
PDF is generated in memory and is not written to the repository.
GET /api/reports/{run_id}/bundle returns metadata only. It lists included
sections, artifact references, keyframe index status, and annotated video
reference status. It does not create a zip, copy large videos, embed keyframe
images, or generate new MP4 artifacts.
Permissions and realtime reporting are intentionally outside Full Stage 6 and remain for later stages.
GET /api/analysis-runs
This endpoint returns a DB-first run list. It reads traffic_analysis_runs
first, then falls back to directories found under results/traffic_analysis/
and the in-memory registry for legacy artifact-only runs. Results are
de-duplicated by run_id.
Query parameters:
status: optional run status filter.video_id: optional video id filter.limit: integer from 0 to 1000, default 50.offset: integer greater than or equal to 0, default 0.
Response shape:
{
"items": [
{
"schema_version": "stage6d.v1",
"id": "run_xxx",
"run_id": "run_xxx",
"video_id": "video_xxx",
"status": "completed",
"mode": "offline",
"result_dir": "results/traffic_analysis/run_xxx",
"source": "db",
"metadata": {
"available": true,
"path": "metadata.json",
"status": "available"
},
"manifest": {
"available": true,
"path": "manifest.json",
"status": "available",
"schema_version": "stage6b.v1"
},
"artifact_index": {
"available": true,
"path": "artifact_index.json",
"status": "available"
},
"artifact_summary": {
"detections_csv": {
"status": "available",
"path": "detections.csv",
"record_count": 123
}
}
}
],
"total": 1,
"limit": 50,
"offset": 0
}Behavior:
- Results are sorted by
updated_at,finished_at, orcreated_atdescending, withrun_idas a stable fallback. - Paths are relative or sanitized for frontend use; local absolute paths are not exposed.
sourcemay bedb,manifest,metadata,artifact_index,in_memory_registry, ordirectory_scan.- Invalid JSON in one run's manifest does not make the whole list fail. The
affected run can fall back to metadata or directory scan and marks that file
status as
error. - Stage 6E frontend Dashboard, Video Center, and Analysis Detail consume this response for run counts, recent runs, and artifact status panels.
GET /api/analysis-runs/{run_id}
This endpoint returns the same Stage 6D summary object used by the list API for
one run. It preserves the legacy id field while also exposing run_id.
Behavior:
- Missing run returns 404.
- Summary source can be
db,manifest,metadata,artifact_index,in_memory_registry, ordirectory_scan. - DB rows take precedence over artifact fallback when both exist.
GET /api/analysis-runs/{run_id}/manifest
This endpoint returns a DB-first run manifest/index representation. For DB runs,
it is built from traffic_analysis_runs.artifact_index; for legacy
artifact-only runs, it reads or builds manifest.json from the local run
directory and writes artifact_index.json when the index is missing.
Response shape:
{
"schema_version": "stage6b.v1",
"run_id": "run_xxx",
"video_id": "video_xxx",
"status": "completed",
"created_at": "2026-01-01T00:00:00+00:00",
"updated_at": "2026-01-01T00:00:00+00:00",
"result_dir": "results/traffic_analysis/run_xxx",
"artifacts": {
"metadata": {
"status": "available",
"path": "metadata.json",
"format": "json",
"record_count": 1,
"required": true
},
"flow_counts": {
"status": "available",
"path": "flow_counts.json",
"format": "json",
"record_count": 8,
"required": false
},
"keyframes": {
"status": "available",
"path": "keyframes/",
"format": "directory",
"record_count": 2,
"required": false
},
"keyframes_index": {
"status": "available",
"path": "keyframes/index.json",
"format": "json",
"record_count": 1,
"required": false
},
"annotated_video": {
"status": "missing_source_video",
"path": "annotated_video.mp4",
"format": "mp4",
"record_count": 0,
"required": false
}
}
}Artifact status values:
available: file or non-empty directory exists and can be read.missing: Stage 6B core artifact is expected but not present.planned: later-stage artifact reserved by contract, such asevaluation_summary.json. Older runs without generated Stage 6C statistics may still showflow_counts.jsonorzone_statistics.jsonas planned until those artifacts are generated.empty: artifact exists and is readable, but has zero records.missing_source_video: Stage 6F visual artifact generation could not run because the source video was not available.error: artifact status or count could not be read.
Behavior:
- Missing run returns 404.
- Paths are relative to the run directory.
- Stage 6F
keyframes,keyframes_index, andannotated_videostatus are exposed through this manifest and through the run summaryartifact_summary. - The endpoint does not generate evaluation results.
- Visual artifact generation failures are represented in manifest status and do not imply Review / Bad Case / Evaluation behavior.
GET /api/analysis-runs/{run_id}/trajectory-points
Query parameters:
limit: integer from 0 to 1000, default 100.track_id: optional integer. When set, rows and each frame'strajectory_pointsare filtered to that track.
Response shape:
{
"run_id": "run_xxx",
"video_id": "video_xxx",
"summary": {},
"frames": [],
"rows": [],
"limit": 100,
"track_id": null,
"source": "db"
}Behavior:
- Missing run returns 404.
- Existing run without trajectory DB rows or trajectory artifacts returns 404.
limit=0returnssummarywith emptyframesandrows.track_idfilters trajectory rows and frame-leveltrajectory_points.
GET /api/analysis-runs/{run_id}/events
This endpoint is a DB-first run event query. When DB event rows exist for the
run, it reads events, event_evidence, and rule_executions and returns
source=db. When DB rows are unavailable, it falls back to events.jsonl,
event_evidence.jsonl, rule_executions.jsonl, and event_summary.json from a
local run directory.
Full Stage 3AB also provides top-level /api/events DB-first APIs. When DB rows
are unavailable and run_id is supplied, the top-level list/detail APIs can
fallback to run artifacts.
Top-level Event APIs:
GET /api/events?run_id=&video_id=&event_type=&rule_id=&status=&severity=&track_id=GET /api/events/{event_id}?run_id=PATCH /api/events/{event_id}/statusPOST /api/events/{event_id}/bad-case
PATCH /api/events/{event_id}/status updates the DB event status only. Review
Center actions under /api/review write the review_comments DB audit trail.
POST /api/events/{event_id}/bad-case creates a minimal DB bad-case record
linked to the event, run, video, and track. Full Stage 3EF extends the complete
Bad Case workflow under /api/bad-cases with DB-first create/list/detail/update,
filter, summary, from-review, and from-failed-case behavior.
Query parameters:
limit: integer from 0 to 1000, default 100.event_type: optional string. Filters returned events by event type, such asdanger_zone_intrusion,pedestrian_in_vehicle_lane,illegal_parking,wrong_way_driving,flow_counting, orcongestion.rule_id: optional string. Filters returned events and rule executions by rule id.track_id: optional integer. Filters returned events, event evidence, and rule executions by track.
Response shape:
{
"run_id": "run_xxx",
"video_id": "video_xxx",
"summary": {},
"events": [],
"event_evidence": [],
"rule_executions": [],
"limit": 100,
"event_type": null,
"rule_id": null,
"track_id": null,
"source": "db"
}Behavior:
- Missing run returns 404.
- Existing run without event artifacts returns 404.
limit=0returnssummarywith emptyevents,event_evidence, andrule_executions.- The response does not expose local absolute paths.
- Current implemented rule callbacks are
danger_zone_intrusion,pedestrian_in_vehicle_lane,illegal_parking,wrong_way_driving,flow_counting, andcongestion.
GET /api/analysis-runs/{run_id}/flow-counts
This endpoint returns flow count results DB-first. If DB flow_counts rows are
missing but the run artifacts exist, it falls back to the Stage 6C
flow_counts.json payload. A run with no flow_counting events returns a valid
empty artifact fallback.
Response shape:
{
"schema_version": "stage6.flow_counts.v1",
"run_id": "run_xxx",
"video_id": "video_xxx",
"window_ms": 60000,
"source_artifacts": {
"events": "events.jsonl",
"event_evidence": "event_evidence.jsonl",
"rule_executions": "rule_executions.jsonl"
},
"summary": {
"total_count": 0,
"vehicle_count": 0,
"person_count": 0,
"by_class": {},
"by_zone": {},
"by_line": {},
"by_direction": {}
},
"windows": [],
"records": [],
"source": "db"
}Behavior:
- Missing run returns 404.
- Existing run without
flow_countingevents returns an empty artifact. - Direction values are normalized to
in,out, orunknown. sourceisdbfor persisted rows andartifactfor fallback.- Stage 6E Analysis Detail displays this payload as a minimal summary/table view.
- This is not a frontend chart or real-world calibrated traffic volume system.
GET /api/analysis-runs/{run_id}/zone-statistics
This endpoint returns zone statistics DB-first. If DB zone_statistics rows are
missing but the run artifacts exist, it falls back to the Stage 6C
zone_statistics.json payload. The artifact builder only aggregates explicit
zone information already present in trajectory points and congestion evidence;
it does not infer new zone membership from geometry at query time.
Response shape:
{
"schema_version": "stage6.zone_statistics.v1",
"run_id": "run_xxx",
"video_id": "video_xxx",
"window_ms": 60000,
"source_artifacts": {
"trajectory_points": "trajectory_points.jsonl",
"events": "events.jsonl",
"event_evidence": "event_evidence.jsonl"
},
"summary": {
"zone_count": 0,
"total_windows": 0,
"vehicle_count": 0,
"person_count": 0,
"max_vehicle_count": 0,
"min_avg_speed_px_per_frame": null,
"congestion_event_count": 0
},
"windows": [],
"congestion_events": [],
"source": "db"
}Behavior:
- Missing run returns 404.
- Existing run without zone data returns an empty artifact.
- Congestion rule evidence is preserved as
congestion_events. sourceisdbfor persisted rows andartifactfor fallback.- Stage 6E Analysis Detail displays this payload as a minimal summary/table view.
- This is not a frontend congestion chart or real-world congestion calibration system.
POST /api/analysis-runs/{run_id}/alerts/generate
This endpoint reads existing events.jsonl and generates:
alerts.jsonlalert_summary.json
It does not modify event artifacts. Alert status changes are handled by the
standalone /api/alerts/{alert_id}/... endpoints below.
Response shape:
{
"run_id": "run_xxx",
"video_id": "video_xxx",
"status": "completed",
"total_alerts": 0,
"alert_summary": {},
"artifacts": {}
}Behavior:
- Missing run returns 404.
- Existing run without event artifacts returns 404.
- Alerts are generated from existing event artifacts, not from model inference.
GET /api/analysis-runs/{run_id}/alerts
This endpoint is a DB-first run alert query. When DB alerts rows exist for the
run, it reads them by run_id, applies the same filters, and returns
source=db. When no DB alert rows exist, it falls back to alerts.jsonl and
alert_summary.json from the local run directory. The standalone Alert Center
endpoints below remain DB-first for DB alert rows and fallback to artifact
alerts for legacy runs.
Query parameters:
limit: integer from 0 to 1000, default 100.status: optional string. Currently generated alerts default tonew.level: optional string. Supported generated levels areinfo,warning, andcritical.event_type: optional string. Filters alerts by source event type.
Response shape:
{
"run_id": "run_xxx",
"video_id": "video_xxx",
"summary": {},
"alerts": [],
"limit": 100,
"status": null,
"level": null,
"event_type": null,
"source": "db"
}Behavior:
- Missing run returns 404.
- Existing run without DB alert rows and without alert artifacts returns 404.
limit=0returnssummarywith an emptyalertslist.- Event rule severity remains
low/medium/high; alertlevelremains the alert-center concept and may beinfo,warning, orcritical.
GET /api/alerts
Query parameters:
run_id: optional run id filter.status: optional alert status filter:new,acknowledged,resolved, orignored.level: optional alert level filter:info,warning, orcritical.
Response shape:
{
"alerts": [],
"total": 0,
"run_id": null,
"status": null,
"level": null
}GET /api/alerts/{alert_id} returns one alert or 404.
PATCH /api/alerts/{alert_id}/acknowledge
Optional body:
{
"acknowledged_by": "operator_1"
}Sets status=acknowledged, writes acknowledged_by, and writes
acknowledged_at.
PATCH /api/alerts/{alert_id}/resolve sets status=resolved and writes
resolved_at.
PATCH /api/alerts/{alert_id}/ignore sets status=ignored.
These endpoints update DB alert rows when a matching DB alert exists. If no DB alert is found, they fallback to the current artifact-backed MVP storage.
Stage 7C implements the artifact-backed Review API MVP. Stage 7D adds a React
Review Center MVP that consumes these endpoints for run filters, event
list/detail, confirm, false-positive, ignore, resolve, comments, and
false-negative creation. Stage 7E adds frontend URL navigation into Review
Center from Analysis Detail and Alert Center. Stage 7F audits this as the
Review Center artifact-backed MVP boundary. Full Stage 3CD adds DB-first Review
workflow behavior for DB events: actions update events.status, append
review_comments audit rows, and preserve artifact fallback for legacy runs.
Per-run review artifact files used by these APIs:
review_comments.jsonl: append-only audit trail forconfirm,mark_false_positive,add_false_negative,ignore,resolve, andcommentactions.event_review_state.json: derived current review state keyed byevent_id. It does not overwrite the original Event Engineevents.jsonl.false_negative_events.jsonl: local MVP records for manually added missed events. These records are not Bad Case Center records and are not Evaluation ground truth.
Implemented endpoints:
GET /api/review/events?run_id=&status=&event_type=&limit=50&offset=0GET /api/review/events/{event_id}?run_id=POST /api/review/events/{event_id}/confirmPOST /api/review/events/{event_id}/false-positivePOST /api/review/events/{event_id}/ignorePOST /api/review/events/{event_id}/resolvePOST /api/review/commentsGET /api/review/comments?run_id=&event_id=&limit=50&offset=0POST /api/review/false-negativesPOST /api/review/events/false-negativePOST /api/review/events/{event_id}/rerun-rule
GET /api/review/events requires run_id; this avoids ambiguous global
event_id lookup across local artifact directories. Missing event artifacts for
an existing run return an empty list. Missing review artifacts return empty
comments/state. Malformed review artifacts return 400.
Review event list response shape:
{
"items": [
{
"run_id": "run_xxx",
"event_id": "event_xxx",
"event_type": "danger_zone_intrusion",
"track_id": 17,
"zone_id": "zone_001",
"severity": "high",
"original_status": "pending",
"review_status": "confirmed",
"last_action": "confirm",
"comment_count": 1,
"linked_alert_ids": ["alert_xxx"],
"start_frame": 10,
"end_frame": 12,
"start_time_ms": 900,
"end_time_ms": 1000
}
],
"total": 1,
"limit": 50,
"offset": 0
}Review action request body:
{
"run_id": "run_xxx",
"comment": "confirmed",
"reviewer": "local_reviewer",
"alert_id": null
}Action responses include the current review status, the appended review record,
and the current event review state. For DB events, actions update
events.status and append review_comments. For artifact-only runs, actions
do not overwrite events.jsonl.
POST /api/review/comments appends a comment-only review record. It preserves
the current status and increments comment_count.
POST /api/review/false-negatives writes DB false-negative event/review rows
when the run exists in DB, otherwise it writes false_negative_events.jsonl,
appends an add_false_negative review comment, and updates
event_review_state.json. POST /api/review/events/false-negative is the DB
workflow endpoint and returns the created event_id.
POST /api/review/events/{event_id}/rerun-rule records a request as a
processing_tasks row with mode=rule_rerun and parameters containing
event_id, run_id, rule_id, rerun_scope=event_rules_only,
requested_by, and reason. For DB runs that already have persisted
trajectory_points plus zone / event-rule config, the endpoint replays only
the EventEngine rule layer against the existing trajectory records, appends new
rerun_* event, evidence, and rule execution rows, and marks the task
completed. It does not rerun YOLOv8, DeepSORT, trajectory extraction, or
overwrite previous result rows. If the run has no usable trajectory/config data,
the endpoint still preserves the request as a pending rule-rerun task.
False-negative and rerun endpoints do not automatically create Bad Cases and do not automatically feed Evaluation Center.
Full Stage 5E Review UI uses these endpoints through a ReviewDrawer workflow:
confirm / false-positive / ignore / resolve / comment stay in Review, Review ->
Bad Case calls POST /api/bad-cases/from-review, and rule rerun request records
the event-rules-only rule_rerun task described above.
HTTP behavior:
400: missing requiredrun_id, invalid state transition, or malformed review artifact.404: run or event not found.422: request body validation error.
The Stage 7 frontend did not create Bad Case records or feed Evaluation Center,
and Stage 7E navigation does not auto-sync Alert Center status with Event
review status. Stage 8B adds backend artifact/schema/service support for Bad
Case records. Stage 8CD adds routed Bad Case API and a Bad Case Center frontend
MVP. Full Stage 3EF makes Bad Case DB workflow available under
/api/bad-cases. Full Stage 5E adds an explicit Review -> Bad Case UI action,
but Review API status actions still do not modify Bad Case records
automatically.
Stage 7E frontend URL query contract:
/review?run_id=run_001&event_id=event_123/review?run_id=run_001&event_id=event_123&alert_id=alert_456/review?status=pending/review?run_id=run_001&event_type=wrong_way_driving
Supported query parameters are run_id, event_id, alert_id, status, and
event_type. The Review Center initializes filters from these values. With
run_id + event_id, it loads the matching event detail. With alert_id, it
shows alert context and highlights the linked alert when present. Analysis
Detail only renders a Review link for events; Alert Center only renders a
linked event Review link and keeps acknowledge / resolve / ignore behavior
separate.
Stage 8CD implements an artifact-backed Bad Case API MVP. Full Stage 3EF makes
these endpoints DB-first for DB-backed runs while preserving artifact fallback.
DB rows store core fields in bad_cases and extended fields such as video_id,
track_id, frame_index, module, root_cause, expected_result,
actual_result, snapshot_path, linked_review_id, and
linked_failed_case_id in the JSON payload. Artifact-only runs still read and
write per-run bad_cases.jsonl.
Implemented endpoints:
GET /api/bad-cases?run_id=&video_id=&event_id=&case_type=&module=&status=&tag=&limit=50&offset=0GET /api/bad-cases/{case_id}?run_id=POST /api/bad-casesPATCH /api/bad-cases/{case_id}GET /api/bad-cases/summary?run_id=POST /api/bad-cases/from-reviewPOST /api/bad-cases/from-failed-case
GET /api/bad-cases supports global discovery across run directories when
run_id is omitted. Missing bad_cases.jsonl returns an empty list. Malformed
Bad Case artifacts return 400 with a stable error message.
POST /api/bad-cases/from-review creates a Bad Case that references
DB review_comments.id or review_comments.jsonl.review_id through
linked_review_id; it does not overwrite Review artifacts or original event
artifacts.
POST /api/bad-cases/from-failed-case creates or returns a Bad Case linked to
an Evaluation failed case. It first searches DB
evaluation_results.summary["failed_cases"], then falls back to
evals/results/failed_cases.jsonl. It writes source=evaluation_center and
linked_failed_case_id=<failed_case_id>. The endpoint is idempotent for the
same run_id and failed_case_id: if a Bad Case already links that failed
case, the existing record is returned. It does not mutate failed case source
records.
HTTP behavior:
400: malformed Bad Case artifact or unsupported business update.404: analysis run, Bad Case, Review record, or Evaluation failed case not found.422: request body validation error, including unsupported enum values.
Stage 8HI adds artifact-backed failed case conversion and Bad Case regression summary MVP. Full Stage 3EF adds DB-backed Bad Case workflow and failed-case conversion. Full Stage 4CD adds annotation-backed detection / tracking benchmark rows for tiny fixtures. Full Stage 4E adds deterministic replay / rule replay regression for Bad Cases. Complete video-level rerun is still not implemented.
Stage 8EFG / Stage 8HI implements an artifact-backed Evaluation API MVP. Full
Stage 3EF adds DB-first Evaluation workflow using evaluation_datasets and
evaluation_results. Failed cases are persisted inside
evaluation_results.summary["failed_cases"]; no separate failed-cases table is
introduced in this stage. Artifacts remain available under
evals/datasets/evaluation_datasets.json, evals/results/, and per-run
evaluation_summary.json.
Available endpoints:
GET /api/evaluation/datasetsPOST /api/evaluation/datasetsGET /api/evaluation/runsPOST /api/evaluation/runGET /api/evaluation/resultsGET /api/evaluation/summary/{run_id}GET /api/evaluation/failed-cases
POST /api/evaluation/run accepts event, flow_counting, trajectory,
detection, tracking, and regression. Event / flow / trajectory are MVP
comparisons that can be written to DB. Event evaluation writes
event_accuracy, event_precision, event_recall, event_f1, and
false_alarm_rate; the details payload also includes per-event-type metrics
where available. Detection writes detection_mAP, detection_precision,
detection_recall, and detection_ap_<class> when annotation fixtures are
available. Tracking writes tracking_idf1, tracking_mota,
tracking_id_switches, and tracking_track_lost when annotation fixtures are
available; ID switches and lost tracks are also emitted as Evaluation failed
cases with suggested Bad Case types id_switch and track_lost. Without
annotations, detection / tracking return insufficient_data with
reason=not_enough_annotations and do not emit fake benchmark numbers.
Detection mAP is VOC-style single-IoU AP, not COCO official mAP. Tracking
metrics are lightweight deterministic frame-level association, not TrackEval
official implementation. Regression reads Bad Case DB rows or bad_cases.jsonl
and uses config filters such as case_type, module, status, tag, and
apply_updates. It writes per-case replay results plus
regression_pass_rate, failed_case_count, fixed_case_count, and
reopened_case_count. apply_updates defaults to false; when true, passed open
/ triaged cases are marked fixed, while failed fixed / verified cases are
reopened as open. Missing replay payload returns insufficient_data and does
not emit a fake pass. This does not execute a complete video-level rerun
pipeline.
Full Stage 5E Evaluation UI presents run / dataset / type filters, result cards,
JSON-friendly result details, failed-case -> Bad Case conversion, regression
summary, and the same non-COCO / non-TrackEval / deterministic replay /
insufficient_data boundary labels.
Full Stage 7AB adds DB-backed camera CRUD for realtime preview configuration.
Supported source_type values are upload, rtsp, file, and mock.
Normal responses do not return the full stream_url; they return
masked_stream_url instead. Do not commit real RTSP addresses, local video
paths, secrets, or generated realtime outputs.
Available endpoints:
POST /api/camerasGET /api/cameras?source_type=&enabled=GET /api/cameras/{camera_id}PATCH /api/cameras/{camera_id}DELETE /api/cameras/{camera_id}POST /api/cameras/{camera_id}/enablePOST /api/cameras/{camera_id}/disable
Camera response fields include id, name, location, source_type,
masked_stream_url, enabled, status, width, height, fps,
metadata, created_at, and updated_at. stream_url is accepted on create
and update so the backend can store configuration, but it is not exposed by the
default response models.
HTTP behavior:
400: unsupported source type.404: camera not found.422: request body validation error.
Full Stage 7AB adds a lightweight realtime preview service. It is a metadata
preview, not production realtime monitoring. It does not open real RTSP
connections, does not run Celery or a complex queue, and does not generate video
or frame artifacts. Start creates a DB processing_tasks row with
mode=realtime_process and a lightweight realtime pseudo-video row so the
existing processing task contract remains linked.
Available endpoints:
POST /api/realtime/{camera_id}/startPOST /api/realtime/{camera_id}/stopGET /api/realtime/{camera_id}/statusGET /api/realtime/{camera_id}/recent-framesGET /api/realtime/{camera_id}/recent-eventsGET /api/realtime/{camera_id}/recent-alerts
Preview behavior:
mock: generates deterministic recent frame metadata plus one preview event and one preview alert.file: performs local file smoke-level metadata preview and returns only a safe source label such as the basename.rtsp: accepts masked RTSP configuration and returns a no-connect preview status without network dependency.upload: returns upload-preview placeholder metadata.
Recent frames / events / alerts are kept in a bounded in-memory cache
(max_items=20 per camera). Disabled cameras return 400 on start. Missing
cameras return 404. Full Stage 7CD adds minimal actor / permission / audit /
readiness hardening around these endpoints. Production IAM, central audit
storage, operations monitoring, and production realtime streaming remain
outside the current local preview.
The following API capabilities are planned by the execution manual but are not implemented as working behavior yet:
- advanced filtering on flow counts and zone statistics
- production-grade aggregate statistics APIs
- complete video-level Bad Case rerun pipeline
- COCO official mAP / TrackEval official evaluation
- production realtime monitoring and production IAM
Stage 8EFG / Stage 8HI Evaluation APIs are routed under /api/evaluation and
documented above.
These placeholder endpoints exist to preserve module boundaries. Standalone
event and alert center APIs remain separate from the artifact-based
analysis-runs list, summary, event, statistics, and alert endpoints
documented above. Review API MVP is available under /api/review, the Stage 7
Review Center frontend consumes it, and Stage 7F confirms the artifact-backed
Review Center MVP boundary. Stage 8CD adds artifact-compatible Bad Case APIs
and frontend workflow. Stage 8EFG adds Evaluation APIs and frontend workflow.
Stage 8HI adds failed case conversion and Bad Case regression summary MVP. Full
Stage 3EF makes Bad Case and Evaluation DB-first with artifact fallback.
Complete video-level rerun, COCO official metrics, TrackEval official metrics,
and production hardening remain outside the current implementation.