Skip to Content
APIRecordings

Recordings

A recording is one take, and its files are the tracks: a video file, and on desktop and mobile a WAV master beside it. Every track carries its capture manifest, a record of what the recorder actually produced rather than what was asked for.

curl https://capturly.app/api/v1/recordings/{id} \ -H "Authorization: Bearer cap_live_..."

Endpoints

MethodPath
GET/v1/recordings — ready recordings, newest first; filter with session_id
GET/v1/recordings/{id}
POST/v1/recordings/{id}/files/{fileId}/download-url — a short-lived signed URL

Reading needs recordings:read; minting a download URL needs recordings:download.

A track

{ "id": "file_...", "kind": "video", "contentType": "video/mp4", "sizeBytes": 734003200, "durationSec": 1820, "participantLabel": "Sam", "consent": null, "md5": "XrY7u+Ae7tCTyyK7j1rNww==", "checksum": { "algorithm": "md5", "base64": "XrY7u+Ae7tCTyyK7j1rNww==", "hex": "5eb63bbbe01eeed093cb22bb8f5acdc3", "source": "object-store" }, "capture": { "audioSampleRate": 48000, "audioBitDepth": null, "audioChannels": 2, "audioCodec": "mp4a.40.2", "videoCodec": "avc1.640028", "videoWidth": 1920, "videoHeight": 1080, "videoFrameRate": 30, "framesDropped": 0, "syncBeepAtMs": 1200, "surface": "desktop", "device": "Logitech BRIO", "deviceType": "usb", "appVersion": "2.15.0", "capturedAt": "2026-11-13T12:00:00.000Z", "watermarked": false } }

The capture manifest

FieldMeaning
audioSampleRate, audioBitDepth, audioChannels, audioCodecThe audio in this file. On a WAV master they come from the file’s own header
videoWidth, videoHeight, videoFrameRate, videoCodecThe picture in this file. Null on a WAV
framesDroppedVideo frames lost during the take. 0 is a clean take
syncBeepAtMsOffset of the 1 kHz alignment tone from the start of the file
surfaceWhat recorded it: web, desktop, ios, android or sdk
deviceThe microphone (audio track) or camera (video track) as the operating system named it. Always null on capture-request tracks
deviceTypeWhat kind of input it was: built-in, wired, usb, bluetooth, virtual or unknown
appVersionThe version of the app or SDK that recorded it
capturedAtWhen recording started, by the recorder’s clock
watermarkedWhether the free-tier mark is in the frames

durationSec sits on the track itself.

A value the recorder could not observe is null, never a plausible zero. Two cases you will meet:

  • framesDropped is null for Android takes, and for browsers without a camera drop counter (Firefox, Safari) unless the WebCodecs recorder counted it.
  • Tracks recorded by a client older than this field are null across the manifest.

The manifest is reported by the recorder. Treat it as provenance, not as a measurement Capturly re-derived from the file.

Capture-request tracks

A track recorded for a capture request is a respondent’s, not yours, so it never carries the device’s name: an operating system names devices after their owner (“Jane’s AirPods”). device is null and deviceType says what kind it was. Capturly drops the name on the server even if a client sends one.

These tracks also carry consent, the release the respondent accepted. It is the same record GET /v1/capture-requests/{id}/submissions returns:

FieldMeaning
textThe release verbatim, as it was displayed. Editing the request later never changes it
textSha256SHA-256 (hex) of text
versiondefault:v1, custom:<sha>, or legacy for records backfilled at migration, which are not evidence of what was seen
acceptedAtWhen they accepted
ipAddress, subjectName, subjectEmailCaptured at acceptance; email is null for open-link takes. Only returned to a key that also has capture_requests:read. For any other key these three fields are left out of the response, not set to null

consent is null on every other track, and on a take whose request asked for no release. Webhook payloads go to your own endpoint and always carry the full record.

The checksum

checksum is never sent by the recorder. It is the MD5 of the stored bytes:

  • object-store: computed by storage as the upload landed.
  • server: storage could not hash it (a WAV master assembled from a live backup, for one), so Capturly read the stored file back and hashed it. This happens within the hour; until then checksum is null.

MD5, not SHA-256, because storage computes it for free on every upload while the bytes are already passing through. A SHA-256 would mean either reading every file back after upload or trusting a hash the recording device sent. Use it to confirm a download is intact: md5sum prints the hex form.

Last updated on