REST API: Archive & Historical Video Playback Endpoints

The Archive API provides access to recorded fMP4 video footage, timeline availability intervals, on-demand HLS streaming, and MP4 clip downloads.

---

1. Query Timeline Recording Intervals (GET /api/cameras/:id/archive)

Scans the camera's recording directory and returns available fMP4 intervals:

• Required Role: viewer, operator, or admin

curl -H "Authorization: Bearer <TOKEN>" http://localhost:8080/api/cameras/cam-01/archive

Response (200 OK):

[
  {
    "start": "2026-08-23T14:00:00Z",
    "end": "2026-08-23T15:00:00Z",
    "filename": "2026-08-23_14-00-00_to_15-00-00.mp4"
  },
  {
    "start": "2026-08-23T15:00:00Z",
    "end": "2026-08-23T15:45:12Z",
    "filename": "2026-08-23_15-00-00_ongoing.mp4"
  }
]

---

2. On-Demand Archive HLS Playlist (GET /hls/:id/archive.m3u8)

Streams historical video over HLS for a specific archive file:

curl "http://localhost:8080/hls/cam-01/archive.m3u8?file=2026-08-23_14-00-00_to_15-00-00.mp4"

The server parses fMP4 box offsets via internal/archive/hls.go and dynamically generates the M3U8 manifest referencing GET /hls/:id/segment.ts?file=...&seq=0.

---

3. Export Seamless MP4 Video Clip (GET /api/cameras/:id/export)

Extracts continuous video parts from an fMP4 recording and streams them as a standalone MP4 file:

• Query Parameters:
  • file (string, required): Filename in camera archive directory
  • start_seq (integer, optional, default 0): Starting part sequence index
  • end_seq (integer, optional, default last): Ending part sequence index

curl -H "Authorization: Bearer <TOKEN>" \
  "http://localhost:8080/api/cameras/cam-01/export?file=2026-08-23_14-00-00_to_15-00-00.mp4&start_seq=0&end_seq=10" \
  -o exported_clip.mp4

Response headers:

HTTP/1.1 200 OK
Content-Type: video/mp4
Content-Disposition: attachment; filename="export_cam-01.mp4"

Related Documentation

• REST API Reference
• Archive Storage Overview
• Archive Playback Guide
• Web UI Archive Player