Recordings

Recordings capture user flows from the Aiqaramba Recorder browser extension. Each recording contains rrweb DOM events (clicks, typing, scrolling, navigation) and optionally tab video with audio. Recordings can be converted into user journeys for automated replay.

POST /api/v1/recordings

Create a new recording

Upload a recording captured by the browser extension. Events are stored as compressed JSON in cloud storage. If has_video is true, the response includes a presigned URL for uploading the video file directly to storage.

Parameters

ParameterTypeInRequiredDescription
namestringbodyNoRecording name
started_attimestampbodyYesWhen the recording started (ISO 8601)
ended_attimestampbodyNoWhen the recording ended
duration_msintegerbodyNoRecording duration in milliseconds
event_countintegerbodyNoNumber of rrweb events captured
eventsjsonbodyYesArray of rrweb event objects
navigationsjsonbodyNoArray of navigation events with url and timestamp_ms
project_iduuidbodyNoAssociate recording with a project
has_videobooleanbodyNoWhether video will be uploaded separately
has_audiobooleanbodyNoWhether the video includes audio

Status Codes

CodeDescription
201Recording created
400Validation error
401Unauthorized

Response Body

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "status": "uploading",
  "video_upload_url": "https://storage.googleapis.com/bucket/path?X-Goog-Signature=..."
}
POST /api/v1/recordings
cURL 
Response 
GET /api/v1/recordings 
List recordings
Parameters
ParameterTypeInRequiredDescription
 
limitintegerqueryNoNumber of results (max 100) (default: 25)
cursoruuidqueryNoCursor for pagination 
project_iduuidqueryNoFilter by project 
statusstringqueryNoFilter by status: uploading, processing, ready, failed 
Status Codes
CodeDescription
 
200OK
401Unauthorized
Response Body
{
  "recordings": [{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440000",
  "user_id": "110e8400-e29b-41d4-a716-446655440000",
  "name": "Login flow recording",
  "status": "ready",
  "started_at": "2026-05-04T10:00:00Z",
  "ended_at": "2026-05-04T10:02:30Z",
  "duration_ms": 150000,
  "event_count": 1247,
  "has_video": true,
  "has_audio": true,
  "navigations": [{"url": "https://app.example.com/login", "timestamp_ms": 0}],
  "journey_id": null,
  "created_at": "2026-05-04T10:02:31Z",
  "updated_at": "2026-05-04T10:02:35Z"
}],
  "next_cursor": null
}
GET /api/v1/recordings
 
 
 
 
 
cURL 
Response 
GET /api/v1/recordings/{id} 
Get recording details
Parameters
ParameterTypeInRequiredDescription
 
iduuidpathYesRecording ID 
Status Codes
CodeDescription
 
200OK
404Recording not found
401Unauthorized
Response Body
{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440000",
  "user_id": "110e8400-e29b-41d4-a716-446655440000",
  "name": "Login flow recording",
  "status": "ready",
  "started_at": "2026-05-04T10:00:00Z",
  "ended_at": "2026-05-04T10:02:30Z",
  "duration_ms": 150000,
  "event_count": 1247,
  "has_video": true,
  "has_audio": true,
  "navigations": [{"url": "https://app.example.com/login", "timestamp_ms": 0}],
  "journey_id": null,
  "created_at": "2026-05-04T10:02:31Z",
  "updated_at": "2026-05-04T10:02:35Z"
}
GET /api/v1/recordings/{id}
 
 
cURL 
Response 
GET /api/v1/recordings/{id}/events 
Stream recording events
Returns the full rrweb event array as JSON. Events are decompressed from cloud storage on the fly. Response can be large for long recordings.
Parameters
ParameterTypeInRequiredDescription
 
iduuidpathYesRecording ID 
Status Codes
CodeDescription
 
200OK — JSON array of rrweb events
404Recording not found
401Unauthorized
Response Body
[{"type": 4, "data": {"href": "https://app.example.com/login"}, "timestamp": 1714816800000}, ...]
GET /api/v1/recordings/{id}/events
 
 
cURL 
Response 
POST /api/v1/recordings/{id}/video-complete 
Confirm video upload
Call after uploading the video file to the presigned URL. Verifies the video exists in storage and transitions the recording to processing status.
Parameters
ParameterTypeInRequiredDescription
 
iduuidpathYesRecording ID 
Status Codes
CodeDescription
 
200Video confirmed, processing started
404Recording not found
409Video not yet uploaded
401Unauthorized
Response Body
{"status": "processing"}
POST /api/v1/recordings/{id}/video-complete
 
 
cURL 
Response 
DELETE /api/v1/recordings/{id} 
Delete a recording
Deletes the recording, its stored events, and associated video file.
Parameters
ParameterTypeInRequiredDescription
 
iduuidpathYesRecording ID 
Status Codes
CodeDescription
 
204Deleted
404Recording not found
401Unauthorized
DELETE /api/v1/recordings/{id}
 
 
cURL 
Response