🔒 HD Relay API Documentation

REST API reference for the HD Relay VSaaS platform · v2.0

Base URL: https://hdrelay.io/api
Authentication: All endpoints (except login and health) require a Bearer token.
Authorization: Bearer <token> — obtain via POST /api/login
Token lifetime: 24 hours. Re-authenticate when expired.

Sections:
Authentication Cameras Sites Users Recordings & Timeline Archive & Clips AI Detection Timelapse PTZ Control Social Push Bandwidth & Storage Dashboard Health & Monitoring Cloud Storage Branding & Layout Landing Page Clip Sharing

🔑 Authentication

POST /api/login PUBLIC

Authenticate and receive a JWT token.

body.username: string — required
body.password: string — required
→ token: JWT token (24h expiry)
→ name, role: User display name and role (admin/client)

# Authenticate and capture token
curl -s -X POST https://hdrelay.io/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])"

GET /api/health PUBLIC

Health check — returns {"status":"ok"}.

curl -s https://hdrelay.io/api/health

📷 Cameras

GET /api/cameras AUTH

List cameras visible to the authenticated user. Clients only see assigned cameras.

curl -s https://hdrelay.io/api/cameras \
  -H "Authorization: Bearer $TOKEN"

GET /api/admin/cameras ADMIN

List all cameras with full details (IP, credentials, config).

POST /api/admin/cameras ADMIN

Add a new camera. Auto-syncs to mediamtx.yml.

body: name, ip, rtspPort, user, pass, brand, streamPath, ptz, siteId, location, streamServer, timezone

curl -s -X POST https://hdrelay.io/api/admin/cameras \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Entrance",
    "ip": "192.168.1.100",
    "rtspPort": 554,
    "user": "admin",
    "pass": "password",
    "brand": "hikvision",
    "streamPath": "Streaming/Channels/101",
    "ptz": false,
    "streamServer": "west"
  }'

PUT /api/admin/cameras/:id ADMIN

Update camera settings. Accepts all fields from POST plus overlay, playerConfig, ticker, apiOverlays.

DELETE /api/admin/cameras/:id ADMIN

Delete a camera and remove from mediamtx.

POST /api/admin/cameras/test AUTH

Test RTSP connectivity to a camera.

body: ip, rtspPort, user, pass, streamPath, brand

PUT /api/admin/cameras/:id/detection ADMIN

Update detection mode, zone, sensitivity, and object classes.

body.mode: "off" | "motion" | "yolo" | "both"
body.zone: {x, y, w, h} normalized 0-1, or null to clear
body.sensitivity: {motion: 0-100, ai: 0-100}
body.detectClasses: ["person","car","truck","motorcycle","bus","dog","cat","bird"]

PUT /api/admin/cameras/:id/retention ADMIN

Update recording mode, retention, schedule, and timelapse flag.

body.days: 7 | 14 | 30 | 60 | 90 — continuous retention
body.eventRetention: 7-365 — detection event retention (days)
body.recording: boolean — enable/disable continuous recording
body.recordingMode: "continuous" | "detection" | "both" | "off"
body.schedule: {enabled: bool, from: "HH:MM", to: "HH:MM"}
body.timelapse: boolean — enable/disable timelapse capture

🏢 Sites

GET/api/admin/sitesADMIN

List all sites.

POST/api/admin/sitesADMIN

Create a site. Body: name, location.

PUT/api/admin/sites/:idADMIN

Update a site.

DELETE/api/admin/sites/:idADMIN

Delete a site.

👤 Users

GET/api/admin/usersADMIN

List all users (passwords excluded).

POST/api/admin/usersADMIN

Create a user. Body: name, username, password, role, cameras[], sites[].

DELETE/api/admin/users/:idADMIN

Delete a user.

PUT/api/admin/users/:id/passwordADMIN

Change user password. Body: password.

PUT/api/admin/users/:id/permissionsADMIN

Update user permissions. Body: cameras[], sites[], permissions object.

🎬 Recordings & Timeline

GET/api/timeline/:camIdAUTH

Get recording timeline index for a camera. Returns hourly MP4 files with dates, sizes, durations.

GET/api/recordings/:camIdAUTH

List raw recording files for a camera.

POST/api/recordings/range/estimateAUTH

Estimate file count and size for a date/time range. Body: camId, from, to.

POST/api/recordings/range/buildAUTH

Build a merged MP4 from a date range (max 24h). Returns jobId for polling.

GET/api/recordings/range/status/:jobIdAUTH

Poll merge job status. Returns progress, url when complete.

GET/api/recordings/range/tarAUTH

Stream hourly files as a TAR archive. Query: camId, from, to. Any length.

🗂 Archive & Clips

GET/api/clip/:camIdAUTH

Extract a clip from a recording. Query: start (ISO), duration (seconds).

🔍 AI Detection

POST/api/detection/alertINTERNAL

Receive detection alerts from the detection engine. Body: camId, label, confidence, snapshotUrl.

GET/api/detection/alertsAUTH

Get recent detection alerts. Query: limit (default 50).

POST/api/detection/alerts/readAUTH

Mark all alerts as read.

GET/api/detection/events/:camIdAUTH

List detection event clips for a camera. Query: date (YYYY-MM-DD), limit.

GET/api/detection/snapshots/:camIdAUTH

List detection snapshots (JPEG) for a camera. Last 100.

POST/api/detection/liveINTERNAL

Post live detection boxes from engine. Body: camId, boxes[], frameW, frameH.

GET/api/detection/live/:camIdAUTH

Get latest live detection overlay boxes for a camera.

⏱ Timelapse

GET/api/timelapse/statusAUTH

Get status of all timelapse capture jobs (active, count, interval).

POST/api/timelapse/startAUTH

Start timelapse capture. Body: camId, intervalMinutes.

POST/api/timelapse/stopAUTH

Stop timelapse capture. Body: camId.

GET/api/timelapse/images/:camIdAUTH

List timelapse JPEG snapshots. Query: from, to (YYYY-MM-DD date filters).

GET/api/timelapse/builds/:camIdAUTH

List timelapse video builds (compiled MP4s).

POST/api/timelapse/buildAUTH

Build a timelapse MP4 video from snapshots. Body: camId, fps.

🎮 PTZ Control

POST/api/ptzAUTH

Send PTZ command. Body: camId, action (pan/tilt/zoom/home/stop), value.

GET/api/ptz/presets/:camIdAUTH

List saved PTZ presets for a camera.

POST/api/ptz/presetAUTH

Go to a preset position. Body: camId, preset.

POST/api/ptz/preset/saveAUTH

Save current position as a preset. Body: camId, name.

GET/api/social/statusAUTH

Get active social push streams.

POST/api/social/startAUTH

Start pushing camera stream to YouTube/Facebook. Body: camId, platform, streamKey, streamUrl.

POST/api/social/stopAUTH

Stop a social push. Body: camId.

📊 Bandwidth & Storage

GET/api/bandwidthAUTH

Get per-camera bandwidth and data usage estimates. Query: period (day|week|month).

GET/api/admin/cameras/:id/storageADMIN

Get detailed storage usage for a camera.

POST/api/admin/cameras/:id/cleanupADMIN

Manually trigger cleanup for a camera. Body: force (boolean).

📈 Dashboard

GET/api/dashboardAUTH

Get full dashboard summary: camera statuses, storage, disk usage, recording stats, live push count.

🏥 Health & Monitoring

GET/api/health/camerasAUTH

Get health status of all cameras (online/offline, last check time, uptime).

GET/api/health/cameras/:camIdAUTH

Get health history for a specific camera.

POST/api/health/email-configADMIN

Configure alert email settings. Body: provider, to, smtpUser, smtpPass, smtpHost, smtpPort.

POST/api/health/test-emailADMIN

Send a test email to verify configuration.

☁ Cloud Storage

GET/api/b2/recordings/:camIdAUTH

List recordings stored in the cloud for a camera. Query: date (YYYY-MM-DD).

GET/api/b2/stream/:camId/:filenameAUTH

Stream (proxy) a cloud recording file for playback.

GET/api/b2/download/:camId/:filenameAUTH

Download a cloud recording file.

GET/api/b2/statsAUTH

Get cloud storage stats (total size, file counts per camera).

GET/api/b2/timelapse/images/:camIdAUTH

List timelapse snapshots in the cloud. Query: from, to (YYYY-MM-DD).

GET/api/b2/snapshots/:camIdAUTH

List detection snapshots in the cloud for a camera.

GET/api/b2/events/:camIdAUTH

List detection event clips in the cloud for a camera.

🎨 Branding & Layout

GET/api/brandingAUTH

Get branding config for the current user (colors, logo, company name).

POST/api/admin/brandingADMIN

Update branding settings. Body: companyName, primaryColor, accentColor, etc.

GET/api/layoutAUTH

Get layout configuration for the current user's role.

PUT/api/admin/layout/:roleADMIN

Update layout visibility for a role. Body: hidden element IDs array.

🌐 Landing Page

GET/api/landing-configPUBLIC

Get landing page CMS configuration (hero text, sections, visibility).

PUT/api/admin/landing-configADMIN

Update landing page content and section visibility.

POST/api/clips/shareAUTH

Create a public share link for a clip. Body: camId, file, expiresIn (hours). Returns HMAC-signed URL.

GET/api/clips/sharedAUTH

List active shared clip links.

DELETE/api/clips/shared/:shareIdAUTH

Revoke a shared clip link.

GET/shared/:shareIdPUBLIC

Access a shared clip (public, HMAC-verified, time-limited).

HD Relay API v2.0 · 80+ endpoints · Generated April 2026