Speed Event Videos

Speed violation events can include optional video evidence captured by edge devices.

Create Speed Event With Video Metadata

POST /api/v1/speed-events

The existing batch speed-event ingest accepts optional video metadata on each event:

{
  "events": [
    {
      "localId": "edge-evt-123",
      "targetId": 42,
      "eventType": 2,
      "linePosition": 12.4,
      "crossingDirection": 1,
      "speedKmh": 78,
      "timestamp": 1778918400000,
      "videoUrl": "https://example-edge-store/evt-123.mp4",
      "videoMetadata": {
        "contentType": "video/mp4",
        "sizeBytes": 18432000,
        "durationMs": 8000,
        "width": 1920,
        "height": 1080,
        "frameRate": 25,
        "codec": "h264"
      }
    }
  ]
}

Response entries include the remoteId used for later uploads.

Upload Video Evidence

POST /api/v1/video-upload

multipart/form-data fields:

Field	Required	Description
eventId	Yes	SpeedEvent UUID returned by ingest
video	Yes	Video file, max 100 MB
durationMs	No	Video duration in milliseconds
width	No	Encoded width
height	No	Encoded height
frameRate	No	Frames per second
codec	No	Codec name, for example h264

Supported content types: video/mp4, video/webm, video/quicktime, video/x-matroska.

Alternate event-scoped endpoint:

POST /api/v1/speed-events/{eventId}/video

This endpoint uses the same multipart body, except eventId is taken from the URL.

Retrieve or Download Video

GET /api/v1/speed-events/{eventId}/video

Streams the video with Content-Type, Content-Length, and Accept-Ranges headers for browser playback.

Use ?download=1 to return an attachment disposition:

GET /api/v1/speed-events/{eventId}/video?download=1

The event detail API also returns:

{
  videoPath: string | null;
  videoUrl: string | null;
  videoMetadata: {
    contentType?: string;
    sizeBytes?: number;
    filename?: string;
    uploadedAt?: string;
    durationMs?: number | null;
    width?: number | null;
    height?: number | null;
    frameRate?: number | null;
    codec?: string | null;
  } | null;
  hasVideo: boolean;
}

Edge Device Notes

Upload video only after ingest succeeds, using the returned remoteId. Keep clips short, preferably 5-15 seconds around the violation, to stay below the 100 MB upload limit and preserve playback performance. For larger evidence packages, upload the file to external storage and pass videoUrl plus videoMetadata during speed-event ingest.