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 tests for automated replay.

GET /api/v1/recordings

List recordings

Parameters

Parameter	Type	In	Required	Description
`limit`	integer	query	No	Maximum recordings to return.
`cursor`	uuid	query	No	Continue below this recording ID.
`project_id`	uuid	query	No	Restrict recordings to one project.
`status`	string	query	No	Restrict recordings to one processing status.
`source_type`	string	query	No	Restrict recordings to one source.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/recordings" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Tenant recordings.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`recordings`	object[]
`recordings[].id`	uuid
`recordings[].tenant_id`	uuid
`recordings[].project_id`	uuid
`recordings[].user_id`	uuid
`recordings[].name`	string
`recordings[].source_type`	string	Values: extension, upload, posthog.
`recordings[].status`	string	Values: uploading, processing, ready, failed.
`recordings[].started_at`	date-time
`recordings[].ended_at`	date-time
`recordings[].duration_ms`	integer
`recordings[].event_count`	integer
`recordings[].has_video`	boolean
`recordings[].has_audio`	boolean
`recordings[].video_mime_type`	string
`recordings[].video_bytes`	integer
`recordings[].navigations`	object[]
`recordings[].uploaded_video_id`	uuid
`recordings[].test_id`	uuid
`recordings[].draft_test_plan_id`	uuid
`recordings[].error_message`	string
`recordings[].external_ref`	string
`recordings[].agent_id`	uuid
`recordings[].created_at`	date-time
`recordings[].updated_at`	date-time
`next_cursor`	uuid

POST /api/v1/recordings

Create a recording

Stores rrweb events and returns a direct video upload URL when video is expected.

Request Body (application/json)

Field	Type	Required	Description
`name`	string	No	Recording name
`started_at`	date-time	Yes	When the recording started (ISO 8601)
`ended_at`	date-time	No	When the recording ended
`duration_ms`	integer	No	Recording duration in milliseconds
`event_count`	integer	No	Number of rrweb events captured
`events`	json	Yes	Array of rrweb event objects
`navigations`	json	No	Array of navigation events with url and timestamp_ms
`project_id`	uuid	No	Associate recording with a project
`has_video`	boolean	No	Whether video will be uploaded separately
`has_audio`	boolean	No	Whether the video includes audio
`audio_narration`	string	No	Base64 data URL containing microphone narration.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/recordings" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "started_at": "2026-01-01T12:00:00Z",
    "events": {}
  }'

Status Codes

Code	Description
`201`	Recording created.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.
`507`	The tenant does not have enough storage quota.

Response Fields (201)

Field	Type	Description
`id`	uuid
`status`	string	Values: uploading, processing.
`video_upload_url`	uri

GET /api/v1/recordings/{id}

Get a recording

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Recording ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/recordings/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Recording found.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`user_id`	uuid
`name`	string
`source_type`	string	Values: extension, upload, posthog.
`status`	string	Values: uploading, processing, ready, failed.
`started_at`	date-time
`ended_at`	date-time
`duration_ms`	integer
`event_count`	integer
`has_video`	boolean
`has_audio`	boolean
`video_mime_type`	string
`video_bytes`	integer
`navigations`	object[]
`uploaded_video_id`	uuid
`test_id`	uuid
`draft_test_plan_id`	uuid
`error_message`	string
`external_ref`	string
`agent_id`	uuid
`created_at`	date-time
`updated_at`	date-time

DELETE /api/v1/recordings/{id}

Delete a recording

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Recording ID.

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/recordings/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Recording deleted.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

GET /api/v1/recordings/{id}/events

Stream recording events

Streams the decompressed rrweb JSON event array.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Recording ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/recordings/<id>/events" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Decompressed rrweb event JSON.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

POST /api/v1/recordings/{id}/reproduce

Reproduce a recording

Runs an existing generated test or queues test generation from stored events.

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Recording ID.

Request Body (application/json)

Field	Type	Required	Description
`finding_id`	uuid	No	Finding to ground the generated test in; the test prompt then ends with a Verify: line asserting the behavior the finding reports as broken

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/recordings/<id>/reproduce" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "finding_id": "<uuid>"
  }'

Status Codes

Code	Description
`202`	Reproduction queued.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`402`	The tenant has exhausted its run allowance.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (202)

Field	Type	Description
`queued`	boolean
`recording_id`	uuid
`test_id`	uuid
`agent_id`	uuid

POST /api/v1/recordings/{id}/video-complete

Confirm recording video upload

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Recording ID.
`skip_video`	boolean	query	No	Process events without a video object.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/recordings/<id>/video-complete" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Processing started.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`409`	The request conflicts with the current resource state.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`status`	string	Values: processing.