API Overview

The Verriflo API lets you create classrooms, manage participants, and handle recordings programmatically. It's a straightforward REST API—nothing fancy, just JSON over HTTPS.

Base URL

All API requests go to:

https://api.verriflo.com

Every endpoint is versioned under /v1/.

Authentication

Every request requires your Organization ID in the VF-ORG-ID header:

curl -X POST https://api.verriflo.com/v1/room/create \
  -H "VF-ORG-ID: your-organization-id" \
  -H "Content-Type: application/json" \
  -d '{...}'

Find your Organization ID in the Verriflo Dashboard under Organization Settings.

Keep It Secret

Your Organization ID is like an API key. Don't expose it in frontend code or public repositories. All API calls should come from your backend.

Request Format

• Use POST for creating resources (joining classes, starting recordings)
• Use GET for reading resources (listing recordings, checking status)
• Send JSON bodies with Content-Type: application/json

Room Identifiers (roomId)

Every room requires a roomId. This ID must be unique across your entire organization history.

• No Reuse: Once a roomId has been used, it cannot be reused for a new room, even after the original room is destroyed.
• Recommendations: Use UUIDs or descriptive IDs with timestamps (e.g., session-123-2024-01-15) to ensure uniqueness.

Response Format

Every response follows this structure:

{
  "success": true,
  "data": {
    // The actual payload
  }
}

For errors:

{
  "success": false,
  "message": "What went wrong",
  "error": "ERROR_CODE"
}

Available Endpoints

Here's what you can do with the API:

Room Management

Endpoint	Method	Description
/v1/room/create	POST	Create a new classroom session
/v1/room/:roomId/join	POST	Join an existing classroom
/v1/room/:roomId/status	GET	Check room status and participants
/v1/room/:roomId	DELETE	End room and disconnect everyone

Recording

Endpoint	Method	Description
/v1/room/:roomId/recording/start	POST	Start recording a live room
/v1/room/:roomId/recording/stop	POST	Stop an active recording
/v1/room/:roomId/recordings	GET	List all recordings for a room
/v1/room/:roomId/recordings/download	GET	Download recording files

Participants

Endpoint	Method	Description
/v1/participant/sessions	POST	Get session history for a user

Billing

Endpoint	Method	Description
/v1/billing/balance	GET	Check credit balance

System

Endpoint	Method	Description
/v1/health/status	GET	API health check

Rate Limits

We don't have strict rate limits for normal usage, but don't go crazy:

• Reasonable: 100 requests/minute per organization
• Excessive: 1000+ requests/minute (we'll probably reach out)

If you're hitting limits, you're probably doing something inefficient. Let's chat about a better approach.

Error Handling

Common HTTP status codes you'll encounter:

Code	Meaning
200	Success
400	Bad request—missing or invalid parameters
402	Insufficient credits
404	Resource not found (room, organization, etc.)
409	Conflict (e.g., recording in progress)
410	Gone (e.g., recording expired)
422	Unprocessable—organization setup incomplete
500	Our fault—something broke on our end

For the full error reference, see Error Codes.

SDKs & Libraries

• Flutter SDK for mobile apps — Documentation
• Web embedding via iframe — Guide

Example: Create a Classroom

Here's the most common API call—creating a room and getting a join URL:

curl -X POST https://api.verriflo.com/v1/room/create \
  -H "VF-ORG-ID: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "roomId": "math-101",
    "title": "Introduction to Algebra",
    "participant": {
      "uid": "teacher-1",
      "name": "Dr. Smith",
      "role": "TEACHER"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "iframeUrl": "https://live.verriflo.com/iframe/live?token=...",
    "expiresAt": "2023-12-31T23:59:59.000Z"
  }
}

Redirect the instructor to iframeUrl and they're live.