Recording

Control recording for your classrooms. Start recording when a class begins, stop it when needed, list all recordings, and download them.

Recording Storage

Recordings are saved to cloud storage and are available for download for 6 hours after the class ends. After that, they're automatically deleted. If you need permanent storage, download the files within this window using the Download Recordings endpoint.

Start Recording

POST /v1/room/:roomId/recording/start

Begin recording a live room. The recording captures the composite view—exactly what participants see.

Request

Headers

Header	Required	Description
VF-ORG-ID	Yes	Your organization ID
Content-Type	Yes	application/json

URL Parameters

Parameter	Description
roomId	The room to record

Request Body

{
  "options": {
    "showLogo": true,
    "layout": "grid",
    "preset": "H264_1080P_30"
  }
}

Field	Type	Required	Description
options	object	No	Recording configuration
options.showLogo	boolean	No	Show organization logo watermark (default: true)
options.layout	string	No	grid or speaker (default: grid)
options.preset	string	No	Quality preset (see below)

Quality Presets:

Preset	Resolution	Usage
H264_720P_30	720p 30fps	Good quality, smaller files
H264_1080P_30	1080p 30fps	High quality (default)

Example Request

curl -X POST https://api.verriflo.com/v1/room/math-101/recording/start \
  -H "VF-ORG-ID: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "showLogo": true,
      "layout": "grid",
      "preset": "H264_1080P_30"
    }
  }'

Response (200)

{
  "success": true,
  "message": "Recording started",
  "data": {
    "egressId": "EG_abc123xyz",
    "roomId": "math-101",
    "status": "EGRESS_STARTING",
    "startedAt": "2024-01-15T09:05:00.000Z"
  }
}

Field	Type	Description
egressId	string	Unique identifier for this recording job
status	string	Recording status (STARTING → ACTIVE)
startedAt	string	When recording started (ISO date)

---

Stop Recording

POST /v1/room/:roomId/recording/stop

Stop an active recording. The file will be processed and available for download shortly after.

Request

Headers

Header	Required	Description
VF-ORG-ID	Yes	Your organization ID
Content-Type	Yes	application/json

Request Body (Optional)

{
  "egressId": "EG_abc123xyz"
}

Field	Type	Required	Description
egressId	string	No	Specific recording to stop (auto-detected if omitted)

If you don't provide an egressId, we'll stop the active recording for that room.

Example Request

curl -X POST https://api.verriflo.com/v1/room/math-101/recording/stop \
  -H "VF-ORG-ID: your-organization-id" \
  -H "Content-Type: application/json"

Response (200)

{
  "success": true,
  "message": "Recording stopped",
  "data": {
    "egressId": "EG_abc123xyz",
    "status": "EGRESS_ENDING",
    "duration": 3600
  }
}

---

List Recordings

GET /v1/room/:roomId/recordings

Get all recordings for a room—past and current.

Request

curl -X GET https://api.verriflo.com/v1/room/math-101/recordings \
  -H "VF-ORG-ID: your-organization-id"

Response (200)

{
  "success": true,
  "message": "Recordings retrieved",
  "data": [
    {
      "recordingId": "rec_EG_abc123xyz",
      "roomId": "math-101",
      "status": "COMPLETED",
      "startedAt": "2024-01-15T09:05:00.000Z",
      "endedAt": "2024-01-15T10:05:00.000Z",
      "duration": 3600
    }
  ]
}

---

Download Recordings

GET /v1/room/:roomId/recordings/download

Get secure, time-limited download URLs for recordings from a completed class session.

Time-Limited Access

Recordings are only available for 6 hours after a class ends. After that, they are automatically deleted.

Request

Headers

Header	Required	Description
VF-ORG-ID	Yes	Your organization ID

URL Parameters

Parameter	Description
roomId	The room identifier

Example Request

curl -X GET https://api.verriflo.com/v1/room/math-101/recordings/download \
  -H "VF-ORG-ID: your-organization-id"

Response (200)

{
  "success": true,
  "message": "Recordings retrieved successfully",
  "data": {
    "roomId": "math-101",
    "files": [
      {
        "filename": "recording.mp4",
        "downloadUrl": "https://storage.verriflo.com/...?sig=...",
        "size": 157286400,
        "duration": 3600,
        "startedAt": "2024-01-15T09:05:00.000Z",
        "endedAt": "2024-01-15T10:05:00.000Z"
      }
    ],
    "expiresIn": "4h 23m"
  }
}

Field	Type	Description
roomId	string	The room these recordings belong to
files	array	List of recording files
files[].downloadUrl	string	Pre-signed URL for download (valid ~1 hour)
expiresIn	string	Time remaining before recordings are deleted

Errors

Status	Message	What to Do
404	Classroom not found	Check roomId
409	Recording in progress	Wait for class to end
410	Download window expired	Recording deleted (past 6h window)

Recording Statuses

Status	Description
STARTING	Recording is initializing
ACTIVE	Recording in progress
ENDING	Recording is being finalized
COMPLETED	Recording finished, file available
FAILED	Recording failed (check logs)
ABORTED	Recording was aborted

Example: Auto-Download Script (Node.js)

const fs = require("fs");
const https = require("https");

async function saveRecordings(roomId) {
  const response = await fetch(
    `https://api.verriflo.com/v1/room/${roomId}/recordings/download`,
    {
      headers: { "VF-ORG-ID": process.env.VERRIFLO_ORG_ID },
    }
  );

  const data = await response.json();

  if (!data.success) {
    throw new Error(data.message);
  }

  for (const file of data.data.files) {
    const dest = fs.createWriteStream(`./${file.filename}`);
    https.get(file.downloadUrl, (res) => {
      res.pipe(dest);
      dest.on("finish", () => console.log(`Saved ${file.filename}`));
    });
  }
}