API Documentation

Complete guide to integrating MrLive into your applications, IoT devices, cameras, and platforms

Get API Key

Quick Start

🚀 Test in our app first, then copy the working code to your system!

1

Get Your API Key

Log in to your dashboard and create an API key from the API Keys page.

X-API-Key: your-api-key-here

💡 Tip: You can test without API key using our Go Live page first!

2

Register Your Device

Register your device or streaming source using the API.

POST /api/devices/register/
Headers:
  X-API-Key: your-api-key
  Content-Type: application/json

Body:
{
  "device_name": "My Camera",
  "device_type": "ip_camera",
  "stream_protocol": "rtsp",
  "stream_url": "rtsp://camera-ip:554/stream"
}

JavaScript Example:

const API_KEY = 'your-api-key';
const BASE_URL = 'http://127.0.0.1:8000';

async function registerDevice() {
  const response = await fetch(`${BASE_URL}/api/devices/register/`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      device_name: 'My Camera',
      device_type: 'ip_camera',
      stream_protocol: 'rtsp',
      stream_url: 'rtsp://camera-ip:554/stream'
    })
  });
  
  const data = await response.json();
  console.log('Device registered:', data);
  return data;
}

Response:

{
  "device_id": "dev_abc123",
  "device_secret": "secret_xyz789",
  "device_name": "My Camera",
  "status": "registered",
  "created_at": "2025-01-15T10:30:00Z"
}
3

Start Streaming

Start streaming from your device using the device ID and secret.

POST /api/devices/{device_id}/start-stream/
Headers:
  X-API-Key: your-api-key
  X-Device-Secret: device-secret

💡 Test First: Use the interactive demo below to test streaming before integrating!

JavaScript Example:

async function startStream(deviceId, deviceSecret) {
  const response = await fetch(`${BASE_URL}/api/devices/${deviceId}/start-stream/`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'X-Device-Secret': deviceSecret
    }
  });
  
  const data = await response.json();
  console.log('Stream started:', data);
  return data;
}

Response:

{
  "session_id": "sess_xyz789",
  "streaming_url": "https://mrlive.com/room/stream-abc123",
  "room_slug": "stream-abc123",
  "status": "active",
  "started_at": "2025-01-15T10:35:00Z"
}

IoT Devices Integration

Connect security cameras, smart devices, and sensors

Python Example

import requests

API_KEY = "your-api-key"
BASE_URL = "https://your-mrlive-server.com"

# Register IoT device
response = requests.post(
    f"{BASE_URL}/api/devices/register/",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "device_name": "Security Camera 1",
        "device_type": "iot",
        "stream_protocol": "rtsp",
        "stream_url": "rtsp://camera-ip:554/stream",
        "location": "Front Entrance",
        "manufacturer": "Hikvision",
        "model": "DS-2CD2142"
    }
)

device = response.json()
device_id = device["device_id"]
device_secret = device["device_secret"]

# Start streaming
stream_response = requests.post(
    f"{BASE_URL}/api/devices/{device_id}/start-stream/",
    headers={
        "X-API-Key": API_KEY,
        "X-Device-Secret": device_secret
    }
)

session = stream_response.json()
print(f"Stream URL: {session['streaming_url']}")

JavaScript/Node.js Example

const API_KEY = 'your-api-key';
const BASE_URL = 'https://your-mrlive-server.com';

// Register device
async function registerDevice() {
  const response = await fetch(`${BASE_URL}/api/devices/register/`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      device_name: 'IoT Sensor Camera',
      device_type: 'iot',
      stream_protocol: 'rtsp',
      stream_url: 'rtsp://sensor-ip:554/stream',
      location: 'Warehouse A'
    })
  });
  
  return await response.json();
}

// Start streaming
async function startStream(deviceId, deviceSecret) {
  const response = await fetch(`${BASE_URL}/api/devices/${deviceId}/start-stream/`, {
    method: 'POST',
      headers: {
        'X-API-Key': API_KEY,
        'X-Device-Secret': deviceSecret
      }
  });
  
  return await response.json();
}

// Usage
(async () => {
  const device = await registerDevice();
  console.log('Device registered:', device);
  
  const session = await startStream(device.device_id, device.device_secret);
  console.log('Stream started:', session);
})();

Register Response:

{
  "device_id": "dev_abc123",
  "device_secret": "secret_xyz789",
  "device_name": "IoT Sensor Camera",
  "status": "registered"
}

IP Cameras & CCTV Integration

Connect IP cameras, CCTV systems, and surveillance cameras

Common RTSP URLs

  • Hikvision: rtsp://username:password@ip:554/Streaming/Channels/101
  • Dahua: rtsp://username:password@ip:554/cam/realmonitor?channel=1&subtype=0
  • Reolink: rtsp://username:password@ip:554/h264Preview_01_main
  • Axis: rtsp://ip:554/axis-media/media.amp

JavaScript Example

const API_KEY = 'your-api-key';
const BASE_URL = 'http://127.0.0.1:8000';

async function registerCamera(cameraInfo) {
  const response = await fetch(`${BASE_URL}/api/devices/register/`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      device_name: cameraInfo.name,
      device_type: 'ip_camera',
      stream_protocol: 'rtsp',
      stream_url: cameraInfo.rtsp_url,
      location: cameraInfo.location,
      manufacturer: cameraInfo.manufacturer || '',
      model: cameraInfo.model || ''
    })
  });
  
  return await response.json();
}

// Register multiple cameras
const cameras = [
  { name: 'Front Door', rtsp_url: 'rtsp://...', location: 'Entrance' },
  { name: 'Parking Lot', rtsp_url: 'rtsp://...', location: 'Parking' }
];

for (const camera of cameras) {
  const device = await registerCamera(camera);
  console.log('Registered:', device.device_id);
}

Response:

{
  "device_id": "dev_abc123",
  "device_secret": "secret_xyz789",
  "device_name": "Front Door",
  "status": "registered"
}

Note: RTSP cameras require FFmpeg conversion to HLS for web playback. See Device Setup Guide for details.

Mobile App Integration

iOS, Android, React Native, Flutter

JavaScript/React Native Example

const API_KEY = 'your-api-key';
const BASE_URL = 'http://127.0.0.1:8000';

// Register mobile device
async function registerDevice() {
  const response = await fetch(`${BASE_URL}/api/devices/register/`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      device_name: 'Mobile Camera',
      device_type: 'mobile',
      stream_protocol: 'webrtc',
      location: 'User Location'
    })
  });
  
  return await response.json();
}

// Start streaming from camera
async function startStream(deviceId, deviceSecret) {
  // Request camera permission (React Native)
  // const { status } = await Camera.requestCameraPermissionsAsync();
  // if (status !== 'granted') throw new Error('Camera permission denied');

  const response = await fetch(`${BASE_URL}/api/devices/${deviceId}/start-stream/`, {
    method: 'POST',
      headers: {
        'X-API-Key': API_KEY,
        'X-Device-Secret': deviceSecret
      }
  });
  
  return await response.json();
}

Response:

{
  "device_id": "dev_mobile123",
  "device_secret": "secret_mobile789",
  "session_id": "sess_xyz456",
  "streaming_url": "https://mrlive.com/room/stream-mobile123"
}

Web Application Integration

React, Vue, Angular, or any JavaScript framework

React/JavaScript Example

\n );\n}`)" class="copy-btn">Copy
import React, { useState, useEffect } from 'react';

const API_KEY = 'your-api-key';
const BASE_URL = 'http://127.0.0.1:8000';

function StreamComponent() {
  const [streamUrl, setStreamUrl] = useState(null);

  useEffect(() => {
    const startStream = async () => {
      // Register device
      const deviceResponse = await fetch(`${BASE_URL}/api/devices/register/`, {
        method: 'POST',
          headers: {
            'X-API-Key': API_KEY,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          device_name: 'Web Camera',
          device_type: 'webcam',
          stream_protocol: 'webrtc'
        })
      });

      const device = await deviceResponse.json();

      // Start streaming
      const streamResponse = await fetch(`${BASE_URL}/api/devices/${device.device_id}/start-stream/`, {
        method: 'POST',
          headers: {
            'X-API-Key': API_KEY,
            'X-Device-Secret': device.device_secret
          }
      });

      const streamData = await streamResponse.json();
      setStreamUrl(streamData.streaming_url);
    };

    startStream();
  }, []);

  return (
    <div>
      {streamUrl && (
        <iframe
          src={streamUrl}
          width="800"
          height="600"
          frameBorder="0"
          allow="autoplay; encrypted-media"
        />
      )}
    </div>
  );
}

Response:

{
  "device_id": "dev_webcam123",
  "device_secret": "secret_webcam789",
  "session_id": "sess_webcam456",
  "streaming_url": "https://mrlive.com/room/stream-webcam123",
  "room_slug": "stream-webcam123"
}

API Reference

Device Endpoints

POST /api/devices/register/

Register a new device

GET /api/devices/

List all devices

GET /api/devices/{device_id}/

Get device details

PUT /api/devices/{device_id}/

Update device

POST /api/devices/{device_id}/start-stream/

Start streaming

POST /api/devices/{device_id}/stop-stream/

Stop streaming

🌐 Multi-Platform Simulcast (Stream to Multiple Platforms)

Stream to your app AND multiple social platforms (Facebook, YouTube, LinkedIn, etc.) simultaneously with one API call!

1

Setup Platforms (One-Time)

First, configure your streaming platforms. Do this once, then reuse for all streams.

// Get your platforms
GET /api/broadcasts/simulcast/

// Create a platform
POST /api/broadcasts/simulcast/
{
  "name": "My Facebook Live",
  "platform": "facebook",
  "stream_url": "rtmps://live-api-s.facebook.com:443/rtmp/",
  "stream_key": "YOUR_FB_STREAM_KEY",
  "is_active": true
}
2

Start Stream (Goes to App + All Platforms)

One API call streams to your app AND all configured platforms automatically!

// Start broadcast - streams to app + all platforms
POST /api/broadcasts/start/
{
  "preset_id": "your-preset-id"
}

// Response:
{
  "room_slug": "adminlive-abc123",
  "destinations": [
    { "platform": "facebook", "status": "active" },
    { "platform": "youtube", "status": "active" },
    { "platform": "linkedin", "status": "active" }
  ]
}
3

Complete Working Code (Copy & Use)

JavaScript/Web App:
// ============================================
// COMPLETE SIMULCAST INTEGRATION
// ============================================

const API_BASE = window.location.origin + '/api';
const TOKEN = 'your-auth-token'; // Get from login

// Step 1: Get user's platforms
async function getPlatforms() {
  const res = await fetch(`${API_BASE}/broadcasts/simulcast/`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` }
  });
  return res.json();
}

// Step 2: Start stream (goes to app + all platforms)
async function goLive(presetId) {
  const res = await fetch(`${API_BASE}/broadcasts/start/`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ preset_id: presetId })
  });
  return res.json();
}

// Step 3: Use it!
(async () => {
  // Get platforms
  const platforms = await getPlatforms();
  console.log('Platforms:', platforms);
  
  // Start stream (use preset_id from Broadcast Manager)
  const result = await goLive('your-preset-id');
  
  console.log('✅ Stream started!');
  console.log('Room:', result.room_slug);
  console.log('Streaming to:', result.destinations);
  
  // Embed in your app
  const streamUrl = `/room/${result.room_slug}/`;
  embedStream(streamUrl);
})();

// Helper: Embed stream
function embedStream(roomUrl) {
  const container = document.getElementById('stream-container');
  if (!container) {
    console.error('stream-container element not found. Create a div with id="stream-container" in your HTML.');
    return;
  }
  container.innerHTML = 
    '';
}
Python:
import requests

BASE_URL = 'https://your-domain.com'
TOKEN = 'your-auth-token'

# Step 1: Get platforms
platforms = requests.get(
    f'{BASE_URL}/api/broadcasts/simulcast/',
    headers={'Authorization': f'Bearer {TOKEN}'}
).json()
print(f'Platforms: {len(platforms)}')

# Step 2: Start stream (goes to app + all platforms)
result = requests.post(
    f'{BASE_URL}/api/broadcasts/start/',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'Content-Type': 'application/json'
    },
    json={'preset_id': 'your-preset-id'}
).json()

print(f'✅ Stream started: {result["room_slug"]}')
print(f'Streaming to: {[d["platform"] for d in result["destinations"]]}')

✅ Supported Platforms:

Facebook Live YouTube Live LinkedIn Live Twitch Twitter/X Instagram TikTok Custom RTMP

📹 IP Camera Simulcast

Stream from IP cameras to your app AND social platforms simultaneously.

⚠️ Security Notice

IP cameras may be in private spaces. Explicit consent required for social media streaming.

POST /api/camera/start-simulcast/
Headers:
  Authorization: Bearer {token}
  Content-Type: application/json

Body:
{
  "camera_url": "rtsp://admin:password@192.168.1.100:554/stream",
  "explicit_consent": true,
  "consent_text": "I confirm authorization to stream to social media"
}
// JavaScript Example
async function streamCamera(cameraUrl) {
  const res = await fetch('/api/camera/start-simulcast/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRFToken': getCookie('csrftoken')
    },
    body: JSON.stringify({
      camera_url: cameraUrl,
      explicit_consent: true,
      consent_text: 'I confirm authorization to stream to social media'
    })
  });
  return res.json();
}

// Use it
const result = await streamCamera('rtsp://admin:pass@192.168.1.100:554/stream');
console.log('Stream started:', result.room_slug);

📋 All API Endpoints

GET /api/broadcasts/simulcast/

Get all configured platforms

POST /api/broadcasts/simulcast/

Create a new platform destination

POST /api/broadcasts/start/

Start broadcast (streams to app + all platforms)

POST /api/camera/start-simulcast/

Stream IP camera to app + platforms

POST /api/start-live/

Start a live session

POST /api/stop-live/{session_id}/

Stop a live session

GET /api/lives/active/

List active sessions

🚀 Developer Workflow

Test first in our app, then copy working code to your system

1

Test in Our App First

Before writing code, test the features in our web interface to understand how they work.

2

Use Interactive Demo Below

Test API calls directly in this page. See real responses and understand the flow.

Scroll down to "Test & Generate Code" section

3

Copy Working Code

After testing, use the "Generated Code" section to get copy-paste ready code for your platform.

Select your platform (JavaScript, Python, React, etc.) and copy the complete working code

4

Integrate into Your System

Paste the code into your application. It's already tested and working!

Test API Connection

Verify your API key and test the connection

Note: The test will check your API key against the /api/pusher-config/ endpoint to verify authentication.

Cluster "ap2": This is the Pusher cluster region identifier. Common regions include: ap2 (Asia Pacific - Singapore), us2 (US East), eu (Europe), us3 (US West). Choose the region closest to your users for best performance.

Live Code Generator & Demo

Generate working code, test connection, and copy ready-to-use code for your devices

Step 1: Register Your Device

Step 2: Start Streaming

Note: Complete Step 1 first to get device credentials.

⚡ Quick Start - Direct Webcam Integration

No login, no registration! Just click and test - works for everyone!

FREE TEST

Ready to stream

Click "Start Streaming" to begin

Integration Code (Copy & Paste)
// Simple Webcam Streaming Integration
// DEMO MODE: No API key needed for testing!
// For production, add your API key

const BASE_URL = window.location.origin; // or your server URL

async function startWebcamStream() {
  try {
    // 1. Request camera access
    const stream = await navigator.mediaDevices.getUserMedia({
      video: { width: 1280, height: 720 },
      audio: true
    });
    
    // 2. Register device automatically in DEMO MODE (no API key needed!)
    const deviceResponse = await fetch(`${BASE_URL}/api/devices/register/`, {
      method: 'POST',
      headers: {
        'X-Demo-Mode': 'true',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        device_name: 'Webcam Stream',
        device_type: 'webcam',
        stream_protocol: 'webrtc',
        location: 'Browser',
        demo_mode: true
      })
    });
    
    const device = await deviceResponse.json();
    
    // 3. Start streaming (demo mode)
    const streamResponse = await fetch(
      `${BASE_URL}/api/devices/${device.device_id}/start-stream/`,
      {
        method: 'POST',
        headers: {
          'X-Demo-Mode': 'true',
          'X-Device-Secret': device.device_secret,
          'Content-Type': 'application/json'
        }
      }
    );
    
    const streamData = await streamResponse.json();
    
    // 4. Show video and stream URL
    const video = document.getElementById('myVideo');
    if (video) {
      video.srcObject = stream;
      video.play();
    }
    
    console.log('Stream URL:', streamData.streaming_url);
    return streamData;
  } catch (error) {
    console.error('Error:', error);
  }
}

// Call it when ready - works without login or API key!
startWebcamStream();

✨ Perfect for testing! This demo works without login or API key. Just click "Start Streaming" and test immediately. For production, use your own API key.

🎥 Live Streaming Demo (Full Control)

Test streaming with full device registration workflow

Ready to stream

Complete registration and start stream to begin

💡 How it works: This demo uses your webcam to create a real stream. After registering a device and starting the stream, you'll see your video feed here. You can share the stream URL with others to view your stream in real-time!

📋 Copy Working Code

After testing above, get copy-paste ready code here