VEverdun
cameras

Post Camera Health Sample

post/cameras/{camera_id}/health-samples

Request

  • Base URL
    https://api.verdun.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://api.verdun.ai/cameras/{camera_id}/health-samples
  • Auth
    API key in header X-API-Key

Path parameters

camera_idstring required

Request body

captured_atstring date-time required

Worker clock at frame capture. Upsert key together with the camera id — re-posting the same captured_at updates the existing sample rather than duplicating it.

snapshot_keystring nullable

S3 key of the captured JPEG under this camera's health-snapshots prefix. Null when no frame could be extracted this tick. A key outside health-snapshots/{camera_id}/ is rejected with 422.

sharpnessnumber nullable

Normalized Laplacian variance, 0..1; higher is sharper. Null when no frame.

luminancenumber nullable

Mean grayscale luminance, 0..1. Null when no frame.

frame_hashstring nullable

64-bit dHash of the frame as 16 lowercase hex chars. Equality with the previous sample's hash is what advances identical_run.

occlusion_pctnumber nullable

Percentage of the frame that is flat and unlike the reference image. Null when no frame OR no reference image is set — a missing measurement, not zero.

shift_pctnumber nullable

How far the view has shifted from the reference image, 0..100. Null when no frame OR no reference image is set. Always sent; PTZ suppression happens server-side.

widthinteger nullable

Probed stream width in pixels.

heightinteger nullable

Probed stream height in pixels.

fpsnumber nullable

Probed average frame rate.

bitrate_kbpsinteger nullable

Ingest bitrate of the sampled segment, kbps.

reconnectsinteger

Runner restarts SINCE THE PREVIOUS SAMPLE, scheduled or on-demand — a per-interval delta, never a cumulative counter. The server sums these across every 24h sample (on-demand ones included) for the stream-flapping check, so an on-demand sample must reset the delta exactly as a scheduled one does, or restarts are counted twice.

on_demandboolean

True when this sample answers an operator's re-check request (health_sample_requested_at on the camera-config poll) rather than the hourly schedule. Stored on the row. On-demand samples are excluded from the frozen-frame run, whose threshold is calibrated on hourly spacing; every other check treats them as ordinary samples. Omitted means false, so an ingestor without re-check support posts scheduled samples unchanged.

worker_idstring nullable

Identifier of the ingest worker that produced the sample (ECS task metadata URI); truncated to 512 client-side.

image_versionstring nullable

Container image version of the ingest worker; truncated to 512 client-side.

Example request

{
  "captured_at": "2026-08-22T12:00:00Z",
  "snapshot_key": "health-snapshots/2b1d3f2e-6e78-4d9b-93d6-3c1f9e40a1d4/20260822T120000.123456Z.jpg",
  "sharpness": 0.82,
  "luminance": 0.47,
  "frame_hash": "9f1c3a7d20b45e68",
  "occlusion_pct": 3.1,
  "shift_pct": 1.5,
  "width": 1920,
  "height": 1080,
  "fps": 15,
  "bitrate_kbps": 2048
}

Response

Successful Response

idstring uuid required

The camera_health_samples row id (existing row's id on an upsert).

camera_idstring uuid required

The camera the sample belongs to.

captured_atstring date-time required

Worker clock at frame capture, echoed back.

Changes

No recorded changes to this operation across all 2 revisions of this API.