CDN API

The CDN API provides access to video playback URLs and transcoding status for videos stored in Verriflo's CDN infrastructure.

Base URL

All CDN endpoints are under:

https://api.verriflo.com/v1/cdn

Authentication

All requests require your Organization ID in the VF-ORG-ID header:

curl -X GET https://api.verriflo.com/v1/cdn/videos/video-123/url \
  -H "VF-ORG-ID: your-organization-id"

Get Video Playback URL

Get a signed playback URL for a video. The URL can be used to stream the video in MP4 or HLS format.

Endpoint: GET /v1/cdn/videos/:videoId/url

Path Parameters:

videoId (required): The unique identifier of the video

Request Example:

curl -X GET https://api.verriflo.com/v1/cdn/videos/video-123/url \
  -H "VF-ORG-ID: org_abc123"

Response:

{
  "success": true,
  "data": {
    "type": "hls",
    "url": "https://cdn.verriflo.com/videos/video-123/master.m3u8?token=...",
    "posterUrl": "https://cdn.verriflo.com/videos/video-123/poster.jpg?token=...",
    "status": "completed"
  }
}

Response Fields:

type: Video format ("hls", "mp4", or null if not ready)
url: Signed playback URL (MP4 or HLS). null if video is not ready
posterUrl: Thumbnail/poster image URL. null if not available
status: Video status ("pending", "processing", "completed", "failed")
message (optional): Additional status message

Note:

The signed URL is time-limited for security. URLs typically expire after a set duration (e.g., 1 hour). Request a new URL if needed.
If url is null, the video is still processing. Check the status endpoint or wait before retrying.

Get Video Status

Check the transcoding status and progress of a video.

Endpoint: GET /v1/cdn/videos/:videoId/status

Path Parameters:

videoId (required): The unique identifier of the video

Request Example:

curl -X GET https://api.verriflo.com/v1/cdn/videos/video-123/status \
  -H "VF-ORG-ID: org_abc123"

Response:

{
  "success": true,
  "data": {
    "videoId": "video-123",
    "status": "completed",
    "progress": 100,
    "createdAt": "2024-01-15T10:00:00.000Z"
  }
}

Response Fields:

videoId: The video identifier
status: Transcoding status ("pending", "processing", "completed", "failed")
progress: Transcoding progress percentage (0-100)
createdAt: Video creation timestamp (ISO 8601)

Status Values:

pending: Video uploaded, transcoding not started
processing: Transcoding in progress
completed: Transcoding finished, video ready for playback
failed: Transcoding failed

Error Codes

Code	Meaning
`400`	Bad request - missing or invalid videoId
`401`	Unauthorized - invalid or missing organization ID
`404`	Video not found
`500`	Internal server error

Usage Examples

JavaScript: Get Video URL

async function getVideoUrl(videoId, organizationId) {
  const response = await fetch(
    `https://api.verriflo.com/v1/cdn/videos/${videoId}/url`,
    {
      method: 'GET',
      headers: {
        'VF-ORG-ID': organizationId,
      },
    }
  );

  const result = await response.json();
  
  if (result.success) {
    return result.data.url;
  } else {
    throw new Error(result.message);
  }
}

// Usage
const videoUrl = await getVideoUrl('video-123', 'org_abc123');
console.log('Video URL:', videoUrl);

JavaScript: Check Video Status

async function checkVideoStatus(videoId, organizationId) {
  const response = await fetch(
    `https://api.verriflo.com/v1/cdn/videos/${videoId}/status`,
    {
      method: 'GET',
      headers: {
        'VF-ORG-ID': organizationId,
      },
    }
  );

  const result = await response.json();
  
  if (result.success) {
    return result.data;
  } else {
    throw new Error(result.message);
  }
}

// Usage
const status = await checkVideoStatus('video-123', 'org_abc123');
console.log('Status:', status.status); // "completed"
console.log('Progress:', status.progress); // 100

HTML Video Player

<!DOCTYPE html>
<html>
<head>
  <title>Video Player</title>
</head>
<body>
  <video id="videoPlayer" controls width="800" height="450"></video>

  <script>
    async function loadVideo(videoId, organizationId) {
      try {
        // Get video URL
        const response = await fetch(
          `https://api.verriflo.com/v1/cdn/videos/${videoId}/url`,
          {
            headers: {
              'VF-ORG-ID': organizationId,
            },
          }
        );

        const result = await response.json();
        
        if (result.success) {
          const video = document.getElementById('videoPlayer');
          
          // For HLS format, use hls.js library
          if (result.data.format === 'hls') {
            if (Hls.isSupported()) {
              const hls = new Hls();
              hls.loadSource(result.data.url);
              hls.attachMedia(video);
            } else if (video.canPlayType('application/vnd.apple.mpegurl')) {
              // Native HLS support (Safari)
              video.src = result.data.url;
            }
          } else {
            // MP4 format
            video.src = result.data.url;
          }
        } else {
          console.error('Failed to get video URL:', result.message);
        }
      } catch (error) {
        console.error('Error loading video:', error);
      }
    }

    // Load video
    loadVideo('video-123', 'org_abc123');
  </script>
</body>
</html>

Video Formats

HLS (HTTP Live Streaming)

HLS is the recommended format for adaptive streaming. It automatically adjusts quality based on network conditions.

Format: master.m3u8 playlist file
Compatibility: Works on all modern browsers and devices
Library: Use hls.js for browsers without native HLS support

MP4

Direct MP4 playback for simple use cases.

Format: Single MP4 file
Compatibility: Universal browser support
Use Case: When you need a simple, direct video file

Best Practices

Check Status First: Before requesting a playback URL, check the video status to ensure transcoding is complete.
Handle Expiration: Signed URLs expire. Implement logic to refresh URLs when needed.
Error Handling: Always handle cases where videos might not be ready or transcoding has failed.
CORS: If embedding videos in web pages, ensure your domain is whitelisted in your Verriflo organization settings.
HLS for Adaptive Streaming: Use HLS format for better user experience across different network conditions.

Integration Notes

Videos are typically uploaded through other Verriflo services (e.g., recordings from live classes)
The videoId is provided when a video is created/uploaded
Transcoding happens automatically after upload
Use the status endpoint to poll for completion before requesting playback URLs

Base URL​

Authentication​

Get Video Playback URL​

Get Video Status​

Error Codes​

Usage Examples​

JavaScript: Get Video URL​

JavaScript: Check Video Status​

HTML Video Player​

Video Formats​

HLS (HTTP Live Streaming)​

MP4​

Best Practices​

Integration Notes​