Introduction

Welcome to the BeeStreamed API documentation. This API allows you to interact with the BeeStreamed platform programmatically, enabling you to manage streaming events, analyze viewer data, and engage with your audience.

Authentication

All API requests require authentication using an access token. Include your token in the request header:

Authorization: Basic base64_encode({token_id}:{secret_key})

Core Resources

The API is organized around these main resources:

• Events - Create, manage, and control streaming events
• Analytics - Access viewer statistics and engagement metrics
• Chat - Manage chat messages and Q&A for events
• Client - Access channel information
• Polls - Create and manage polls for audience engagement
• Signup - Manage event registrations and attendees

Rate Limiting

The API implements rate limiting to ensure fair usage:

• 100 requests per minute for standard endpoints
• 3600 requests per minute for authenticated endpoints

If you exceed these limits, you'll receive a 429 Too Many Requests response.

Response Format

All API responses are returned in JSON format and include a status field indicating the HTTP status code.

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200: Success
• 201: Resource created
• 400: Bad request
• 401: Unauthorized
• 403: Forbidden
• 404: Resource not found
• 405: Method not allowed
• 422: Validation error
• 429: Rate limit exceeded
• 500: Server error

Error responses include a message explaining what went wrong.

Authentication with Access Tokens

Overview

All API requests to Beestreamed require authentication using access tokens. Access tokens provide a secure way to authenticate requests without exposing sensitive credentials.

New access tokens can be created in the Manage Panel.

How to Use Access Tokens

Request Headers

Include your access token in the Authorization header of your HTTP request using Basic authentication:

Authorization: Basic base64_encoded({token_id}:{secret_key})

Where base64_encoded({token_id}:{secret_key}) is the Base64 encoding of your token ID and secret key joined by a colon.

Example Request

# If your token_id is "abc123" and secret_key is "xyz789"
# First, encode "abc123:xyz789" in Base64, which gives "YWJjMTIzOnh5ejc4OQ=="

curl -X GET "https://api.beestreamed.com/events" \
  -H "Authorization: Basic YWJjMTIzOnh5ejc4OQ=="

JavaScript Example

const tokenId = 'abc123';
const secretKey = 'xyz789';
const credentials = btoa(`${tokenId}:${secretKey}`);

fetch('https://api.beestreamed.com/events', {
  headers: {
    'Authorization': `Basic ${credentials}`
  }
})
.then(response => response.json())
.then(data => console.log(data));

Token Lifecycle

• Validity: Access tokens are valid until their manually deleted
• Deletion: Tokens can be deleted through the management console

Security Best Practices

1. Never share your token credentials in client-side code or public repositories
2. Store tokens securely in your backend systems
3. Use HTTPS for all API requests to ensure tokens are transmitted securely
4. Apply the principle of least privilege when requesting token scopes

Rate Limiting

Access token requests are subject to rate limiting. The current limits are:

• 5 token requests per minute per IP address
• 100 API calls per minute per token

Exceeding these limits will result in HTTP 429 (Too Many Requests) responses.

Introduction

The Events API allows you to create, manage, and control streaming events for your channel on the BeeStreamed platform. This introduction covers the key concepts and available endpoints.

Available Endpoints

Event Management

• Get Event Details - Retrieve information about a specific event
• Get All Events - List all events for your channel
• Create Event - Create a new streaming event
• Update Event - Modify an existing event
• Delete Event - Remove an event

Event Resources

• Event Image - Get or update event thumbnail images
• Event Stream - Access stream data and status
• Event Log - View event activity logs

Event States

Events can have the following status values:

• idle - Event is created but not yet streaming
• live - Event is currently streaming
• video - Event is showing recorded video content
• done - Event has ended
• force_live - Event is forced to live state (for WebRTC)

Event Features

Each event can have various features enabled or disabled:

• Chat - Real-time messaging during events
• Q&A - Moderated question and answer functionality
• Signup - Registration form for attendees
• Countdown - Timer showing time until event starts
• Video Auto-Switch - Automatically switch to newest content
• Stream Recording - Save live streams as videos

Get Event Details

Get event details for a specific event.

URL : /events/[EVENT_REF]

Method : GET

Authentication required : YES

Rate Limiting:

• Standard: 100 requests/minute
• Authenticated: 3600 requests/minute

Success Response

Code : 200 OK

Authenticated Response

{
    "event_chat": false,
    "event_client_ref": "abcd1234",
    "event_created": "2023-09-21 15:43:05",
    "event_date": "2023-09-23 17:43:05",
    "event_desc": "This is a description of my event",
    "event_embed_domain": null,
    "event_id": 12345678,
    "event_image": "my_cool_thumbnail.jpg",
    "event_mux": "abdcefghijklmnopqrstuvwxyz0123456789",
    "event_mux_playback": null,
    "event_password": null,
    "event_qa": true,
    "event_recurring": 0,
    "event_ref": "abcd12345678",
    "event_signup": null,
    "event_signup_form_msg": null,
    "event_signup_required": false,
    "event_signup_success_msg": null,
    "event_status": "live",
    "event_title": "A cool title",
    "event_user_ref": "ABCD1234",
    "event_webrtc": false
}

Public Response

{
    "event_chat": false,
    "event_date": "2023-09-23 17:43:05", 
    "event_desc": "This is a description of my event",
    "event_mux_playback": null,
    "event_qa": true,
    "event_signup": null,
    "event_signup_form_msg": null,
    "event_signup_required": false,
    "event_signup_success_msg": null,
    "event_status": "live",
    "event_title": "A cool title"
}

Error Responses

Condition : Event not found

Code : 404 NOT FOUND

{
    "message": "Event with REF {event_ref} not found",
    "status": 404
}

Condition : Not authorized to access event

Code : 403 FORBIDDEN

{
    "message": "You are not authorized to access this event",
    "status": 403
}

Notes

• Response fields vary based on authentication level
• Authenticated users receive full event details
• Public access receives limited event details

Get all events

Get all events from the authenticated user.

URL : /events

Method : GET

Parameters

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)
• STRING status (default all) idle, live, done or video
• STRING orderBy (default event created date) created / startDate
• STRING startDateFrom (Start date is start time of event)
• STRING startDateTo
• STRING search (Anything in title or description can be matched here)

Authentication required : YES

Success Response

Code : 200 OK

User API key

[
    {
        "event_chat": false,
        "event_client_ref": "abcd1234",
        "event_created": "2023-09-21 15:43:05",
        "event_date": "2023-09-23 17:43:05",
        "event_desc": "This is a description of my event",
        "event_embed_domain": null,
        "event_id": 12345678,
        "event_image": "my_cool_thumbnail.jpg",
        "event_mux": "abdcefghijklmnopqrstuvwxyz0123456789",
        "event_mux_playback": null,
        "event_password": null,
        "event_qa": true,
        "event_recurring": 0,
        "event_ref": "abcd12345678",
        "event_signup": null,
        "event_signup_form_msg": null,
        "event_signup_required": false,
        "event_signup_success_msg": null,
        "event_status": "live",
        "event_title": "A cool title",
        "event_user_ref": "ABCD1234"
    },
    {
        "event_chat": false,
        "event_client_ref": "abcd1234",
        "event_created": "2023-09-27 12:11:53",
        "event_date": "2023-10-12 10:30:00",
        "event_desc": "I have a different description for my event",
        "event_embed_domain": null,
        "event_id": 87654321,
        "event_image": "this_is_also_a_cool_thumbnail.jpg",
        "event_mux": "0123456789abdcefghijklmnopqrstuvwxyz",
        "event_mux_playback": null,
        "event_password": null,
        "event_qa": true,
        "event_recurring": 0,
        "event_ref": "abcd12345678",
        "event_signup": null,
        "event_signup_form_msg": null,
        "event_signup_required": false,
        "event_signup_success_msg": null,
        "event_status": "video",
        "event_title": "Another really cool title",
        "event_user_ref": "1234ABCD"
    }
]

Notes

• This only works using a user unique API key.

Create a new event

Creating a new event as a user

URL : /events

Method : POST

Authentication required : YES

Success Response

Code : 201 Created

User API key

{
    "event_ref": "abcd12345678",
    "message": "Event created"
}

Notes

• This only works using a user unique API key.
• No parameters are needed to create a new event, to change event details use PATCH on the newly given "event_ref"

Update event data

Update the event data using available parameters

URL : /events/[EVENT REF]

Method : PATCH

Parameters

• STRING title
• STRING desc or description
• STRING date (Must be formatted)
• STRING status (idle, live, video, done or force_live)
• STRING signup_form (Formatted with commas between each input i.e "Name, Email")
• STRING signup_success_msg (You can reference the signup input value with brackets enclosing the input name. i.e [Name])
• STRING signup_form_msg
• STRING signup_terms (Define custom terms for the signup form)
• STRING image (Idle thumbnail of event)
• STRING lang (Choose language of event, default is English "en")
• STRING qa_form_text (Define the text inside the Q&A form)
• BOOL signup (Signup toggle)
• BOOL chat (Chat toggle)
• BOOL qa (Q&A toggle)
• BOOL show_countdown (Countdown toggle)
• BOOL qa_email_required (Toggle email as a required input for joining qa)
• BOOL video_auto_Switch (Automatically switch the video to the newest finished live stream)
• BOOL save_stream_in_videos (Save live stream in to videos when live stream is done)
• BOOL save_stream_in_videos (Save live stream in to videos when live stream is done)
• BOOL show_logo (Toggle logo on event)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Event updated",
    "rows": 1
}

Notes

• This only works using a user unique API key.
• "rows" indicate how many rows were affected. If 0 then nothing was changed.

Delete event

Permanently deletes a specified event

URL : /events/[EVENT REF]

Method : DELETE

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Event deleted",
    "rows": 1
}

Notes

• This only works using a user unique API key.
• "rows" indicate how many rows were affected. If 0 then nothing was changed.

Get event image url

Get image url from specific event

URL : /events/[EVENT REF]/image

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key + Global authentication

{
    "data": {
            "signed_url": "https://liveplatform-bucket-1.s3.eu-central-1.amazonaws.com/images/standard_webinar_dark.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDGV1LWNlbnRyYWwtMSJIMEYCIQCXvhDTLQ7VAixrAZA%2F%2BnxoqTVeiJuVGrc%2FdyDPdRdM4gIhAOGOz8sUW6JCC13ZbWPmIpk3XzFR1zufm8V3mw%2BvQvOcKs4FCNT%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQARoMNjk2NTg4NDM1MzYxIgyBb6AptrtNlTSifcwqogUh9qPiQn9BUECGtrAY54U4Fl%2FjSpfWZz5g4DEOvqDMpM%2F26KASNXnTTj1FGoiuiQTXqpQk5gUhyeHhHVIjgtP74A5j1e37Z4eBFURVlx6VLe%2BkPykJvDnfi0DxmgHa0icUoWEI4z7jfX2s339tQ49TU%2BKLkzL4zXrCiv7wQY%2B%2FTqmt6jQKPISciI7ycYsW4WbHlxvjhNJBA%2BwJqbfshNrZNrXlGvpZBqtRwMfS8EDvgB3BdmjHyg8CuLk8BIdUgbtoiSY0wTLqOU2fqy2DgFQMbLPF6eXxymSznBnRVSi5XF6kwcmiwdYNe2LLGz%2FM40ic3HfAfTU2zgBfU1qY7c5%2BqYYWOEX6jRPH%2BVzKyRduasFy6j1CWzjO3xhVOW1jHx01D96URhv%2B0vJZNDg8c8jxv%2BSfa3CtyRRgQY06Zz5dLDWhYJUuzIf%2F2zV1dljnF8rjrOAbVFQ9XJPzBDWOt151s9mPExEJW2U1Gdr1Oi%2FYjgfTDo4wFJD7s2Reo5l1ZtwDXfLrAU89LjFpaP9hwhyT%2BM40WgKwoG8UawsOEaWS4l5oJrEp6uBzM8sG9XO%2BzG8qEFJddgEynNe0euxhEizQZNZpb3DmuCwNebL%2FRVuot7MYJcY0VEUbB5Yu9SdL6TQ1kX%2BV4DnqIQIxz%2Bic%2FhxqaDJHpis5Eik72yrcLClXbODvbqtuYpjO1bgi8htSL8znTdm7UBRblS8GEtqf%2BGT1WhTmgKFnKedsBo%2FXUSsrl8dxX4DnnsG%2FNoKBKA9fJsemAn95%2FlJpdbxXYDpUeEqY03OQRM65z7ZelJkUCc63AKkK3PDVs6AdxmtqR4E8zUNnzEr6Ywnuh9KBhOnxpIHYMxj3e3yhkEVAv4cpizXUe3XtYNqAEUsYxEckDq3ZMKZ9dTDGm%2F6pBjqwAVpLyJkFjfiXIHU%2B17IJwGh%2B8sJJqoGs0Z9TYt4mPjL40AE8n%2BvTaUiXV471YijkvFUQY100DamD7exBjijFRwhdDhisKyvTil4HTl3VnMM%2Bo2Lx1yStRaxWXEiL6WEkNrr1nAtmHrcchROTnyxeS%2BIbhg2%2FX2BDTfWk3gHLpHKwQ9AHz3zjRtmLxR3nGv5b5KIySaLVBY6s4ZxfZtDmM5JXKQk8Wdp8P1DqFxRy8tcj&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA2EL7H76Q77GABGXP%2F20231030%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20231030T111039Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Signature=688ca0334edefae39057f6371f023d1fc6d85920bd7720c191c51f1f108d4283"
        },
        "status": 200
    }
}

Notes

• The signed url is a temporary url which is only valid for up to 20 minutes, to use the link for longer request a new one

Get filtered MUX stream data

Get stream data from MUX for a specific event; this includes stream status, view data and simulcast targets.

URL : /events/[EVENT REF]/stream

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

{
    "data": {
        "view_data": [
            {
                "views": 0,
                "viewers": 0,
                "updated_at": "0001-01-01T00:00:00Z"
            }
        ],
        "status": "idle",
        "reconnect_window": 60,
        "simulcast_targets": [
            {
                "id": "A1b2C3d4E5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0",
                "passthrough": "Target name",
                "status": "idle",
                "stream_key": "A1B2C3D4-E5F6G7H8-I9J0K1L2-M3N4O5P6",
                "url": "rtmps://global-live.mux.com:443/app"
            }
        ]
    },
    "status": 200
}

Response Fields

View Data

• views : Total number of views for the stream
• viewers : Current number of active viewers
• updated_at : Timestamp of last view data update

Stream Status

• status : Current stream status (idle, active, etc.)
• reconnect_window : Time window in seconds for stream reconnection

Simulcast Targets

• id : Unique identifier for the simulcast target
• passthrough : Display name or identifier for the target
• status : Current status of the simulcast target
• stream_key : Stream key for the target platform
• url : RTMP URL for the target platform

Notes

• The stream status can be used to determine if a stream is currently active
• Simulcast targets show all configured streaming destinations
• View data is updated periodically and may have a slight delay

Get logs from event

Get list of logs from a specific event

URL : /events/[EVENT REF]/log

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

[
    {
        "events_log_client_ref": "g5zp39",
        "events_log_created": "2024-06-19 10:58:48",
        "events_log_event_ref": "bnomxr897pqw",
        "events_log_id": 6561,
        "events_log_ref": "giiqj9jp5q0s",
        "events_log_response": {
            "webrtc": true
        },
        "events_log_type": "update",
        "events_log_user_ref": "E0QRGZ",
        "row_num": 293
    },
    {
        "events_log_client_ref": "g5zp39",
        "events_log_created": "2024-06-19 10:29:56",
        "events_log_event_ref": "bnomxr897pqw",
        "events_log_id": 6556,
        "events_log_ref": "60xvodpldhul",
        "events_log_response": {
            "webrtc": false
        },
        "events_log_type": "update",
        "events_log_user_ref": "E0QRGZ",
        "row_num": 292
    }
]

Get event rtmp key

Get RTMP key from specific event

URL : /events/[EVENT REF]/rtmp

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": {
        "key": "aee49e2b-c0e6-08c7-cea1-56dbd9fafb9b",
        "server": "rtmps://global-live.mux.com:443/app"
    },
    "status": 200
}

Send bulk signup emails

Send bulk emails for signups on specific event

URL : /events/[EVENT REF]/sendemails

Method : POST

Parameters

• BOOL excludeSent (Excludes everyone that has already received an email)
• BOOL excludeNotSent (Excludes everyone that hasn't received an email)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Emails sent successfully",
    "status": 200
}

Notes

• ecludeSent and excludeNotSent cannot be used at the same time

Delete Simulcast Target

Remove a simulcast target from an event

URL : /events/[EVENT REF]/simulcast

Method : DELETE

Query Parameters :

• target_id=[string] : ID of the simulcast target to delete

Authentication required : YES

Success Response

Code : 200 OK

Content

{
    "message": "Simulcast target deleted",
    "status": 200
}

Error Responses

Condition : If target_id is missing

Code : 400 BAD REQUEST

{
    "error": "target_id_required",
    "status": 400
}

Condition : If deletion fails

Code : 400 BAD REQUEST

{
    "error": "delete_failed",
    "status": 400
}

Notes

• The simulcast target must belong to the specified event
• Deleting a target immediately stops the simulcast to that destination

Create Simulcast Target

Create a new simulcast target for a specific event

URL : /events/[EVENT REF]/simulcast

Method : POST

Authentication required : YES

Request Body

{
    "url": "rtmp://a.rtmp.youtube.com/live2",
    "passthrough": "youtube-stream",
    "stream_key": "xxxx-xxxx-xxxx-xxxx"
}

Success Response

Code : 200 OK

Content

{
    "message": "Simulcast target created",
    "status": 200
}

Notes

• Creates a new simulcast target associated with the event
• The request body must include url, passthrough, and stream_key

Start WebRTC Stream

Start WebRTC stream for a specific event

URL : /events/[EVENT REF]/startwebrtcstream

Method : POST

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Livestream started",
    "status": 200
}

Notes

• No parameters are needed to start a WebRTC stream

Stop WebRTC Stream

Stop WebRTC stream for a specific event

URL : /events/[EVENT REF]/stopwebrtcstream

Method : POST

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Livestream ended successfully",
    "status": 200
}

Notes

• No parameters are needed to stop a WebRTC stream

Get current stream stats

Get current stream stats from specific event

URL : /events/[EVENT REF]/stream

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": {
        "reconnect_window": 60,
        "status": "disabled",
        "view_data": [
            {
                "updated_at": "0001-01-01T00:00:00Z",
                "viewers": 0,
                "views": 0
            }
        ]
    },
    "status": 200
}

Create a new event image

Creating a new event image as a user

URL : /events/[EVENT REF]/upload

Method : POST

Parameters

• STRING filename (Full file name with extenstion. Extenstions must be of types png, jpg or jpeg)

Authentication required : YES

Success Response

Code : 201 Created

User API key

{
    "data": {
        "asset_ref": "abcdefgh12345678",
        "upload_url": "https://liveplatform-bucket-1.s3.eu-central-1.amazonaws.com/images/abcdefgh1234.jpg?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDGV1LWNlbnRyYWwtMSJIMEYCIQCXvhDTLQ7VAixrAZA%2F%2BnxoqTVeiJuVGrc%2FdyDPdRdM4gIhAOGOz8sUW6JCC13ZbWPmIpk3XzFR1zufm8V3mw%2BvQvOcKs4FCNT%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQARoMNjk2NTg4NDM1MzYxIgyBb6AptrtNlTSifcwqogUh9qPiQn9BUECGtrAY54U4Fl%2FjSpfWZz5g4DEOvqDMpM%2F26KASNXnTTj1FGoiuiQTXqpQk5gUhyeHhHVIjgtP74A5j1e37Z4eBFURVlx6VLe%2BkPykJvDnfi0DxmgHa0icUoWEI4z7jfX2s339tQ49TU%2BKLkzL4zXrCiv7wQY%2B%2FTqmt6jQKPISciI7ycYsW4WbHlxvjhNJBA%2BwJqbfshNrZNrXlGvpZBqtRwMfS8EDvgB3BdmjHyg8CuLk8BIdUgbtoiSY0wTLqOU2fqy2DgFQMbLPF6eXxymSznBnRVSi5XF6kwcmiwdYNe2LLGz%2FM40ic3HfAfTU2zgBfU1qY7c5%2BqYYWOEX6jRPH%2BVzKyRduasFy6j1CWzjO3xhVOW1jHx01D96URhv%2B0vJZNDg8c8jxv%2BSfa3CtyRRgQY06Zz5dLDWhYJUuzIf%2F2zV1dljnF8rjrOAbVFQ9XJPzBDWOt151s9mPExEJW2U1Gdr1Oi%2FYjgfTDo4wFJD7s2Reo5l1ZtwDXfLrAU89LjFpaP9hwhyT%2BM40WgKwoG8UawsOEaWS4l5oJrEp6uBzM8sG9XO%2BzG8qEFJddgEynNe0euxhEizQZNZpb3DmuCwNebL%2FRVuot7MYJcY0VEUbB5Yu9SdL6TQ1kX%2BV4DnqIQIxz%2Bic%2FhxqaDJHpis5Eik72yrcLClXbODvbqtuYpjO1bgi8htSL8znTdm7UBRblS8GEtqf%2BGT1WhTmgKFnKedsBo%2FXUSsrl8dxX4DnnsG%2FNoKBKA9fJsemAn95%2FlJpdbxXYDpUeEqY03OQRM65z7ZelJkUCc63AKkK3PDVs6AdxmtqR4E8zUNnzEr6Ywnuh9KBhOnxpIHYMxj3e3yhkEVAv4cpizXUe3XtYNqAEUsYxEckDq3ZMKZ9dTDGm%2F6pBjqwAVpLyJkFjfiXIHU%2B17IJwGh%2B8sJJqoGs0Z9TYt4mPjL40AE8n%2BvTaUiXV471YijkvFUQY100DamD7exBjijFRwhdDhisKyvTil4HTl3VnMM%2Bo2Lx1yStRaxWXEiL6WEkNrr1nAtmHrcchROTnyxeS%2BIbhg2%2FX2BDTfWk3gHLpHKwQ9AHz3zjRtmLxR3nGv5b5KIySaLVBY6s4ZxfZtDmM5JXKQk8Wdp8P1DqFxRy8tcj&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA2EL7H76Q77GABGXP%2F20231030%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20231030T112939Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Signature=46bc0d477c2e6749255abf0402c332dfcd5db5162cb881cc441acd02b808165d"
    },
    "message": "Asset created",
    "status": 201
}

Notes

• This creates a new upload url which is valid for up to 20 minutes, whatever is uploaded to this url can be retrieved via the Asset REF.

Introduction

The Analytics API provides access to viewer statistics and engagement metrics for your streams and videos.

Available Endpoints

• Get Overall Analytics - Retrieve summary statistics
• Get Viewer Data - Get detailed viewer information
• Get View Counts - Access view count metrics
• Get Time Series Data - Retrieve time-based analytics
• Get Breakdown Analytics - Get analytics broken down by categories

Analytics Metrics

The API provides access to various metrics:

• Views - Total number of content views
• Viewers - Unique individuals who viewed content
• Watch Time - Total time spent watching content
• Average Watch Time - Average time per viewer
• Engagement - Interaction metrics (chat, polls, Q&A)
• Geographic Distribution - Viewer locations
• Device Types - Platforms used to access content

Timeframes

Most analytics endpoints accept a timeframe parameter to specify the time range for the data:

timeframe=1609459200,1612137600

This represents a start and end timestamp in Unix time format (seconds since epoch).

Authentication

All analytics endpoints require authentication via:

Authorization: Basic {token_id}:{token_secret}

Rate Limiting

Analytics endpoints follow the standard rate limiting:

• Standard: 100 requests/minute
• Authenticated: 3600 requests/minute

Common Parameters

Many analytics endpoints support these common parameters:

• timeframe : Comma-separated Unix timestamps (start,end)
• limit : Number of results per page (default varies by endpoint)
• page : Page number for pagination

Get overall analytics data

Get aggregate metrics for an event.

URL : /analytics/[EVENT REF]/overall

Method : GET

Authentication required : YES

Query Parameters :

• metric_id : Type of metric to measure (default: "views")
• measurement : Type of measurement to perform (default: "count")
• timeframe : Unix timestamps in seconds (format: "start_timestamp,end_timestamp")

Success Response

Code : 200 OK

{
    "data": {
        "metric": "metric_name",
        "value": "aggregate_value",
        "measurement": "measurement_type"
    },
    "status": 200
}

Error Responses

Condition : Not authorized to access event

Code : 403 FORBIDDEN

{
    "message": "You are not authorized to access this event",
    "status": 403
}

Notes

• Provides aggregate metrics for the specified timeframe
• Different measurements can be applied to the same metric

Get analytics timeseries data

Get time-based analytics data for viewing patterns.

URL : /analytics/[EVENT REF]/timeseries

Method : GET

Authentication required : YES

Query Parameters :

• group_by : Time unit to group the data by (default: "minute") (options: "day", "hour", "ten_minute", "minute") Timeframe must be less than 1 hour for "minute" and 6 hours for "ten_minute".
• timeframe : Unix timestamps in seconds (format: "start_timestamp,end_timestamp")

Success Response

Code : 200 OK

{
    "data": [
        {
            "timestamp": "unix_timestamp",
            "value": "view_count"
        }
    ],
    "status": 200
}

Error Responses

Condition : Not authorized to access event

Code : 403 FORBIDDEN

{
    "message": "You are not authorized to access this event",
    "status": 403
}

Notes

• Data points are grouped by the specified time unit
• Timeframe must be valid Unix timestamps in seconds

Get analytics breakdown data

Get analytics data grouped by specific criteria for an event.

URL : /analytics/[EVENT REF]/breakdown

Method : GET

Authentication required : YES

Query Parameters :

• metric_id : Type of metric to analyze (default: "views")
• group_by : (Required) Criteria to group the data by
• timeframe : Unix timestamps in seconds (format: "start_timestamp,end_timestamp")

Success Response

Code : 200 OK

{
    "data": [
        {
            "group": "group_value",
            "value": "metric_value"
        }
    ],
    "status": 200
}

Error Responses

Condition : Missing required group_by parameter

Code : 400 BAD REQUEST

{
    "message": "Group by is required",
    "status": 400
}

Condition : Not authorized to access event

Code : 403 FORBIDDEN

{
    "message": "You are not authorized to access this event",
    "status": 403
}

Notes

• The group_by parameter is required for this endpoint
• Timeframe must be valid Unix timestamps in seconds

Get analytics views data

Get detailed view data for an event.

URL : /analytics/[EVENT REF]/views

Method : GET

Authentication required : YES

Query Parameters :

• timeframe : Unix timestamps in seconds (format: "start_timestamp,end_timestamp")
• limit : Number of results per page (default: 25)
• page : Page number for pagination (default: 1)
• order : Sort order for results (default: "desc", options: "asc" or "desc")

Success Response

Code : 200 OK

{
    "data": {
        "views": [
            {
                "view_id": "string",
                "view_start": "timestamp",
                "view_end": "timestamp",
                "view_duration": "integer"
            }
        ],
        "total_row_count": "integer",
        "timeframe": ["start_timestamp", "end_timestamp"]
    },
    "status": 200
}

Error Responses

Condition : Not authorized to access event

Code : 403 FORBIDDEN

{
    "message": "You are not authorized to access this event",
    "status": 403
}

Notes

• Results are paginated
• View duration is provided in seconds
• Timeframe must be valid Unix timestamps in seconds

Get analytics viewer data

Get detailed viewer data for a specific viewer of an event.

URL : /analytics/[EVENT REF]/viewers/[VIEWER ID]

Method : GET

Authentication required : YES

Query Parameters :

• timeframe : Unix timestamps in seconds (format: "start_timestamp,end_timestamp")
• limit : Number of results per page (default: 25)
• page : Page number for pagination (default: 1)
• order : Sort order for results (default: "desc", options: "asc" or "desc")

Success Response

Code : 200 OK

{
    "data": {
        "viewer_data": {
            "viewer_id": "string",
            "first_view": "timestamp",
            "last_view": "timestamp",
            "total_views": "integer",
            "total_duration": "integer"
        },
        "interaction_data": {
            // Optional additional interaction data if available
        }
    },
    "status": 200
}

Error Responses

Condition : Viewer ID is required

Code : 400 BAD REQUEST

{
    "message": "Viewer ID is required",
    "status": 400
}

Condition : Not authorized to access event

Code : 403 FORBIDDEN

{
    "message": "You are not authorized to access this event",
    "status": 403
}

Notes

• Viewer ID is required in the URL path
• Interaction data is included when available
• Timeframe must be valid Unix timestamps in seconds

Introduction

The Chat API allows you to manage chat messages and interactions for your streaming events.

Available Endpoints

• Get Chat Messages - Retrieve chat messages for an event
• Send Chat Message - Post a new chat message
• Update Chat Settings - Modify chat configuration

Chat Features

The Chat API supports two types of messaging:

• Standard Chat - Public messages visible to all viewers
• Q&A - Moderated questions that can be answered by hosts

Message States

Chat messages can have different status values:

• public - Visible to all viewers
• hidden - Hidden from public view (moderated)

Q&A messages can have these status values:

• new - Newly submitted question
• approved - Question approved for display
• archived - Question archived (no longer active)

Moderation

The API allows for message moderation through the PATCH endpoint, enabling:

• Hiding inappropriate messages
• Approving questions for Q&A
• Adding replies to questions

Authentication

All chat endpoints require authentication via:

Authorization: Basic {token_id}:{token_secret}

Rate Limiting

Chat endpoints follow the standard rate limiting:

• Standard: 100 requests/minute
• Authenticated: 3600 requests/minute

Message Types

The chat system supports two types of messages:

• Regular chat messages
• Q&A messages (when qa=true)

Status Values

Messages can have different status values depending on type:

Chat messages:

• public - Visible to all users
• hidden - Hidden from public view

Q&A messages:

• approved - Approved for display
• archived - Archived and hidden

Get chat messages

Get chat messages in a list form, choose how many results you want and which page you want to see.

URL : /chat/[EVENT REF]

Method : GET

Parameters

• BOOL qa (default false)
• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)

Authentication required : YES

Success Response

Code : 200 OK

User API key

[
    {
        "chat_created": "2023-10-17 15:52:10",
        "chat_deleted_time": null,
        "chat_email": "john@doe.com",
        "chat_event_ref": "abcd12345678",
        "chat_id": 33,
        "chat_message": "I'm writing in the chat right now",
        "chat_name": "John Doe",
        "chat_ref": "1234ABCD",
        "chat_status": "public",
        "row_num": 2
    },
    {
        "chat_created": "2023-10-17 15:57:49",
        "chat_deleted_time": null,
        "chat_email": "joe@mama.com",
        "chat_event_ref": "abcd12345678",
        "chat_id": 34,
        "chat_message": "This is Joe's mama writing",
        "chat_name": "Joe Mama",
        "chat_ref": "ABCD1234",
        "chat_status": "public",
        "row_num": 1
    }
]

Global authentication

[
    {
        "chat_created": "2023-10-17 15:52:10",
        "chat_id": 33,
        "chat_message": "I'm writing in the chat right now",
        "chat_name": "John Doe",
        "chat_ref": "1234ABCD",
        "row_num": 1
    },
    {
        "chat_created": "2023-10-17 15:57:49",
        "chat_id": 33,
        "chat_message": "This is Joe's mama writing",
        "chat_name": "Joe Mama",
        "chat_ref": "ABCD1234",
        "row_num": 1
    }
]

Notes

• The indexStart parameter uses the chat_id / qa_id to know where to start from.
• row_num is used to indicate how many results there are in total when using pagination.

Create new message

Creating a new message on a specific event

URL : /chat/[EVENT REF]

Method : POST

Parameters

• BOOL qa (default false)
• STRING name (required)
• STRING email (required)
• STRING message (required)

Authentication required : YES

Success Response

Code : 201 Created

Global authentication & User API key

{
    "chat_ref": "ABCD1234",
    "message": "Message created"
}

Update message

Update the message data using available parameters

URL : /chat/[EVENT REF]/[CHAT/QA REF]

Method : PATCH

Parameters

• STRING status (Chat: "public, hidden" Q&A: "approved, archived")

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Updated message",
    "rows": 1
}

Notes

• This only works using a user unique API key.
• "rows" indicate how many rows were affected. If 0 then nothing was changed.

Introduction

The Polls API allows you to create and manage interactive polls for your streaming events. This introduction covers the key concepts and available endpoints for poll management.

Available Endpoints

• Get Polls - Retrieve polls for an event
• Create Poll - Create a new poll for an event
• Update Poll - Modify an existing poll
• Delete Poll - Remove a poll
• Get Poll Entries - Retrieve poll responses

Poll Structure

A poll consists of:

• Question - The main poll question
• Options - Available answer choices
• Status - Current state of the poll (active/inactive)

Poll Entries

Poll entries represent viewer responses to polls and include:

• Selected option
• Timestamp
• Viewer identifier

Usage Examples

Creating a Poll

POST /events/{event_ref}/polls

{
  "question": "What feature would you like to see next?",
  "options": [
    "Mobile app",
    "More analytics",
    "Custom branding",
    "API improvements"
  ],
  "active": true
}

Retrieving Poll Results

GET /events/{event_ref}/polls/{poll_ref}/entries

Get polls

Get all polls for an event or get a specific poll

URL : /polls/[EVENT REF] or /polls/[EVENT REF]/[POLL REF]

Method : GET

Parameters (for listing polls)

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)

Authentication required : YES

Success Response

Code : 200 OK

Response for poll list

{
    "data": [
        {
            "poll_ref": "abc123",
            "poll_event_ref": "event123",
            "poll_question": "What is your favorite color?",
            "poll_options": ["Red", "Blue", "Green"],
            "poll_active": true,
            "poll_created": "2024-01-20 15:30:00"
        }
    ],
    "status": 200
}

Response for single poll

{
    "data": {
        "poll_ref": "abc123",
        "poll_event_ref": "event123",
        "poll_question": "What is your favorite color?",
        "poll_options": ["Red", "Blue", "Green"],
        "poll_active": true,
        "poll_created": "2024-01-20 15:30:00"
    },
    "status": 200
}

Create new poll

Create a new poll for a specific event

URL : /polls/[EVENT REF]

Method : POST

Request Body

{
    "question": "What is your favorite color?",
    "options": ["Red", "Blue", "Green"]
}

Authentication required : YES

Success Response

Code : 201 Created

{
    "poll_ref": "abc123",
    "message": "Poll created",
    "status": 201
}

Notes

• Both question and options are required in the request body
• options must be an array of strings

Update poll

Update poll state or add votes to poll options

URL : /polls/[EVENT REF]/[POLL REF]

Method : PATCH

Parameters For updating state:

• BOOL state (Set poll active/inactive state)

For voting:

• BOOL vote (Must be true)
• INT option_index (Index of the option being voted for)
• STRING email (optional)
• STRING name (optional)

Authentication required : YES

Success Response

Code : 200 OK

Response for state update

{
    "message": "Poll state updated",
    "status": 200
}

Response for vote

{
    "message": "Vote updated",
    "updated_rows": 1,
    "status": 200
}

Notes

• Client authentication required for updating poll state
• Email and name are optional when voting but can be used for tracking entries

Delete poll

Delete a specific poll

URL : /polls/[EVENT REF]/[POLL REF]

Method : DELETE

Authentication required : YES

Success Response

Code : 200 OK

{
    "message": "Poll deleted",
    "status": 200
}

Notes

• Client authentication required
• Deleting a poll will also delete all associated entries

Get poll entries

Get all entries for a specific poll

URL : /polls/[EVENT REF]/[POLL REF]/entries

Method : GET

Parameters

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)
• STRING search (Search by email or name)

Authentication required : YES

Success Response

Code : 200 OK

{
    "data": [
        {
            "poll_entry_id": 123,
            "poll_entry_poll_ref": "abc123",
            "poll_entry_email": "user@example.com",
            "poll_entry_name": "John Doe",
            "poll_entry_option_index": 1,
            "poll_entry_created": "2024-01-20 15:30:00",
            "poll_entry_row_number": 1
        }
    ],
    "status": 200
}

Notes

• The row_number field can be used for pagination purposes
• Search parameter will match against both email and name fields

Introduction

The Signup API allows you to manage event registrations and attendee information. This introduction will help you understand how to work with signup data and functionality.

Available Endpoints

• Create Signup - Register an attendee for an event
• Get Signups - Retrieve signup entries for an event
• Update Signup - Modify signup information

Signup Form

Each event can have a customized signup form with various field types:

• Name
• Email
• Phone
• Custom fields

Usage Examples

Creating a Signup

POST /events/{event_ref}/signup

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "custom_field": "Additional information"
}

Get signup details

Get signup details from a specific event

URL : /signup/[EVENT REF]/[SIGNUP REF]

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

{
    "signup_data": 
    {
        "name": "John Doe", 
        "email": "john@doe.com", 
        "company": "Doe Corp."
    },
    "signup_date": "2023-09-06 11:25:35",
    "signup_date_visited": null,
    "signup_email_sent": 1,
    "signup_ref": "abcdefghijklmn1234567890",
    "signup_visited": 0
}

Create new signup

Creating a new signup on a specific event

URL : /signup/[EVENT REF]

Method : POST

Parameters

Parameters may be defined by the users on each event. Check "event_signup" data column under "Get event details" for an example of this.

• STRING name (required)
• STRING email (required)
• STRING message (required)

Authentication required : YES

Success Response

Code : 201 Created

Global authentication & User API key

{
    "signup_ref": "ABCD1234",
    "message": "Signup created"
}

Get all signups

Get all signups from the authenticated user.

URL : /signup/[EVENT REF]

Method : GET

Parameters

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)

Authentication required : YES

Success Response

Code : 200 OK

User API key

[
    {
        "row_num": 2,
        "signup_data": 
        {
            "name": "John Doe", 
            "email": "john@doe.com", 
            "company": "Doe Corp."
        },
        "signup_date": "2023-10-23 22:07:37",
        "signup_date_visited": "2023-10-25 12:14:34",
        "signup_email_sent": 1,
        "signup_event_ref": "abcdefgh1234",
        "signup_id": 12,
        "signup_ref": "abcdefghijklmn1234567890",
        "signup_visited": 1
    },
    {
        "row_num": 1,
        "signup_data":
        {
            "name": "Joe Mama", 
            "email": "joe@mama.com", 
            "company": "Joe's Mama's Bakery"
        },
        "signup_date": "2023-10-23 22:06:09",
        "signup_date_visited": null,
        "signup_email_sent": 0,
        "signup_event_ref": "abcdefgh1234",
        "signup_id": 12,
        "signup_ref": "1234567890abcdefghijklmn",
        "signup_visited": 0
    },
]

Notes

• This only works using a user unique API key.
• The indexStart parameter uses the chat_id / qa_id to know where to start from.
• row_num is used to indicate how many results there are in total when using pagination.

Introduction

The Videos API allows you to manage video content in your Beestreamed account.

Available Endpoints

• Get All Videos - Retrieve a list of all videos
• Get Video Details - Get details for a specific video
• Create Video - Upload a new video
• Update Video - Update video metadata
• Delete Video - Remove a video

Video Upload

• Create Upload Link - Generate a direct upload URL
• Get Upload Status - Check the status of an upload

Video Processing

• Get Video Download Link - Get a download link for the master file

Video States

Videos can have the following status values:

• processing - Video is being processed
• ready - Video is ready for playback
• error - Video processing encountered an error
• deleted - Video has been marked for deletion

Video Features

Each video can have various features enabled or disabled:

• Downloadable - Allow viewers to download the video
• Public/Private - Control video visibility
• Auto-publish - Automatically publish video when processing completes
• Chapters - Define sections within the video
• Custom Thumbnail - Use a custom image as the video thumbnail

Get video details

Get details from a specific video

URL : /videos/[VIDEO REF]

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": {
        "video_client_ref": "g5zp39",
        "video_date": "2024-06-19 10:17:54",
        "video_delete_date": 0,
        "video_deleted": 0,
        "video_delivery_current": 72,
        "video_delivery_next_update": 1719009155,
        "video_delivery_paid": 0,
        "video_event_ref": null,
        "video_id": 275,
        "video_mux_asset_id": "LGbqMZ8lS213tmO1OPCSA9bbqiWorz001iuiO3WG0168Y",
        "video_mux_data": {
            "asset_id": "LGbqMZ8lS213tmO1OPCSA9bbqiWorz001iuiO3WG0168Y",
            "details": {
                "aspect_ratio": "16:9",
                "frame_rate": 24,
                "resolution": "1080p",
                "resolution_tag": "HD"
            },
            "duration": 78.95833333333333,
            "playback_id": "JOlubbhBPwU6HPktGkgrh6T3yzN7EAPe1hdcST6b9pQ"
        },
        "video_mux_sync": 0,
        "video_ref": "pvg36jbfxxmdtochgwjtdcnuyp1tve1o",
        "video_title": "TEST STREAM FOR VIDEOSDK"
    },
    "status": 200
}

Notes

• This only works using a user unique API key.

Get all videos

Get all videos from the authenticated user.

URL : /videos

Method : GET

Parameters

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)
• STRING startDateFrom (Start date is creation date of video)
• STRING startDateTo
• STRING search (Anything in title)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": [
        {
            "row_num": 12,
            "video_client_ref": "g5zp39",
            "video_date": "2024-06-19 10:17:54",
            "video_delete_date": 0,
            "video_deleted": 0,
            "video_delivery_current": 72,
            "video_delivery_next_update": 1719009155,
            "video_delivery_paid": 0,
            "video_event_ref": null,
            "video_id": 275,
            "video_mux_asset_id": "LGbqMZ8lS213tmO1OPCSA9bbqiWorz001iuiO3WG0168Y",
            "video_mux_data": {
                "asset_id": "LGbqMZ8lS213tmO1OPCSA9bbqiWorz001iuiO3WG0168Y",
                "details": {
                    "aspect_ratio": "16:9",
                    "frame_rate": 24,
                    "resolution": "1080p",
                    "resolution_tag": "HD"
                },
                "duration": 78.95833333333333,
                "playback_id": "JOlubbhBPwU6HPktGkgrh6T3yzN7EAPe1hdcST6b9pQ"
            },
            "video_mux_sync": 0,
            "video_ref": "pvg36jbfxxmdtochgwjtdcnuyp1tve1o",
            "video_title": "TEST STREAM FOR VIDEOSDK"
        },
        {
            "row_num": 11,
            "video_client_ref": "g5zp39",
            "video_date": "2024-06-18 14:10:47",
            "video_delete_date": 0,
            "video_deleted": 0,
            "video_delivery_current": 932,
            "video_delivery_next_update": 1719023682,
            "video_delivery_paid": 0,
            "video_event_ref": "wdml7mti13cz",
            "video_id": 274,
            "video_mux_asset_id": "H02LZjuDqHWwSbVo4wlPR024bYNWL1yBZRg8wUyE4jZpA",
            "video_mux_data": {
                "asset_id": "H02LZjuDqHWwSbVo4wlPR024bYNWL1yBZRg8wUyE4jZpA",
                "details": {
                    "aspect_ratio": "16:9",
                    "frame_rate": 25,
                    "resolution": "1080p",
                    "resolution_tag": "UHD"
                },
                "duration": 88.884,
                "playback_id": "w4qmVq51YP0002Pz7ArakmEMYEMWEmHRibqy4p9REnKNQ"
            },
            "video_mux_sync": 1,
            "video_ref": "lio2wth4jyo53pwa8at7uu895vqqez22",
            "video_title": "Experian - Innovation Summit 2024 - with subtitles.mp4"
        },
        {
            "row_num": 10,
            "video_client_ref": "g5zp39",
            "video_date": "2024-06-18 14:06:37",
            "video_delete_date": 0,
            "video_deleted": 0,
            "video_delivery_current": 1528,
            "video_delivery_next_update": 1719023675,
            "video_delivery_paid": 0,
            "video_event_ref": "s3u7ph3tbuvk",
            "video_id": 273,
            "video_mux_asset_id": "Igs01HNyekAvRlakbyP8Mz99wyv1yAgXOUTGXK5oeye00",
            "video_mux_data": {
                "asset_id": "Igs01HNyekAvRlakbyP8Mz99wyv1yAgXOUTGXK5oeye00",
                "details": {
                    "aspect_ratio": "16:9",
                    "frame_rate": 25,
                    "resolution": "1080p",
                    "resolution_tag": "UHD"
                },
                "duration": 66.275667,
                "playback_id": "tYBjsyej01YHC02VSwj004Mi9Y02fCXjwKUeT8F6Na00GSeI"
            },
            "video_mux_sync": 1,
            "video_ref": "whclyu2vput6gplz5yf6x7vjwe1k3216",
            "video_title": "Wunderman20230220_Ad_video_done.mp4"
        },
        {
            "row_num": 9,
            "video_client_ref": "g5zp39",
            "video_date": "2024-06-14 17:46:16",
            "video_delete_date": 0,
            "video_deleted": 0,
            "video_delivery_current": 270,
            "video_delivery_next_update": 1718998347,
            "video_delivery_paid": 0,
            "video_event_ref": null,
            "video_id": 233,
            "video_mux_asset_id": "p42VC2gKhyegTPVaFVFoS63Nkq02PTOhiGwkYdeEL8Xs",
            "video_mux_data": {
                "asset_id": "p42VC2gKhyegTPVaFVFoS63Nkq02PTOhiGwkYdeEL8Xs",
                "details": {
                    "aspect_ratio": "16:9",
                    "frame_rate": 24,
                    "resolution": "720p",
                    "resolution_tag": "HD"
                },
                "duration": 447.75,
                "playback_id": "Qx3KNC9XHJGqjC6VGXP1F6XQgKfykTo388QZsZ12jXk"
            },
            "video_mux_sync": 1,
            "video_ref": "dqnetln5a5kxgd2hp4lly62ef8d6mv4n",
            "video_title": "Upgrading an M1 MacBook Air to 2TB! - SSD Storage Upgrade.mp4"
        },
        {
            "row_num": 8,
            "video_client_ref": "g5zp39",
            "video_date": "2024-06-07 15:11:33",
            "video_delete_date": 0,
            "video_deleted": 0,
            "video_delivery_current": 716,
            "video_delivery_next_update": 1718983924,
            "video_delivery_paid": 0,
            "video_event_ref": null,
            "video_id": 231,
            "video_mux_asset_id": "K6TomEQMuyywCiUsw9gu024Y9Vg7SOWowjrpGEFgaTEQ",
            "video_mux_data": {
                "asset_id": "K6TomEQMuyywCiUsw9gu024Y9Vg7SOWowjrpGEFgaTEQ",
                "details": {
                    "aspect_ratio": "16:9",
                    "frame_rate": 30,
                    "resolution": "1080p",
                    "resolution_tag": "HD"
                },
                "duration": 67.533333,
                "playback_id": "f012Atj3nqKxowRiGrLLKCavFxh00LnMV024re00lRuNZ84"
            },
            "video_mux_sync": 1,
            "video_ref": "hlxg4vd1zqpqbjs4v56f8jn88nh8v508",
            "video_title": "0103-africa.mp4"
        }
    ],
    "status": 200
}

Notes

• This only works using a user unique API key.

Create video

Creating a new video

URL : /videos

Method : POST

Parameters

• STRING title (required)
• STRING asset_id (required) MUX Asset ID

Authentication required : YES

Success Response

Code : 201 Created

User API key

{
    "video_ref": "abcd12345678",
    "message": "Video created",
    "status": 201
}

Notes

• This only works using a user unique API key.

Update video data

Update the video data using available parameters

URL : /videos/[VIDEO REF]

Method : PATCH

Parameters

• STRING title
• STRING event_ref (Create link between event and video)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Event updated",
    "rows": 1
}

Notes

• This only works using a user unique API key.
• "rows" indicate how many rows were affected. If 0 then nothing was changed.
• Creating a link between a video and an event will remove any existing link. Set to null or "" to remove a link without replacing.

Delete video

Permanently deletes a specified video

URL : /videos/[VIDEO REF]

Method : DELETE

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "message": "Video deleted",
    "rows": 1
}

Notes

• This only works using a user unique API key.
• "rows" indicate how many rows were affected. If 0 then nothing was changed.
• Video will still be available, but unwatchable until remaining delivery has been counted.

Create upload link

Creates a new upload link for videos

URL : /videos/upload

Method : POST

Parameters

• INT duration (required) Duration of video in seconds

Authentication required : YES

Success Response

Code : 201 Created

User API key

{
    "data": {
        "data": {
            "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ",
            "timeout": 3600,
            "status": "waiting",
            "new_asset_settings": {
                "playback_policies": [
                    "public"
                ],
                "encoding_tier": "baseline",
                "mp4_support": "capped-1080p"
            },
            "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
            "cors_origin": "https://example.com/"
        }
    },
    "status": 201
}

Notes

• If an upload is already in progress, it will instead return the status of that upload. (Same output as GET /videos/upload/[UPLOAD ID])

Get upload status

Get upload status of specific upload

URL : /videos/upload/[UPLOAD ID]

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
  "data": {
    "timeout": 3600,
    "status": "asset_created",
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ],
      "encoding_tier": "baseline",
      "mp4_support": "capped-1080p"
    },
    "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM",
    "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00"
  }
}

Notes

• This only works using a user unique API key.

Get video download link

Gets master file of video as a download link

URL : /videos/[VIDEO REF]/master

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key + Global authentication

Preparing download

{
    "data": "preparing",
    "status": 200
}

Master download ready

{
    "data": "https://master.mux.com/jEwsJfK02Ae2GQkPacSY4N2uts9EKiJC3/master.mp4?skid=default&signature=NjY3YTkxMWJfN2M0MzMzYzFiMTIyZTJjZjAxZmE1YzgyNDY5YWY0NjcyZDQ0ZjcxMTcxYTY1ZWYyYmIxZmI1NWYwY2RhYTQwMQ==",
    "status": 200
}

Notes

• Depending on the duration and resolution of the video, the preparation of the downlink can vary.

Introduction

The Client API provides access to channel information and management features.

Available Endpoints

• Get Channel Details - Retrieve information about a channel

Channel Connections

• Get All Connections - List all user connections to a channel
• Create Connection - Create a new channel connection
• Delete Connection - Remove a channel connection

Channel Branding

• Get Channel Logo - Retrieve the channel's logo
• Update Channel Logo - Upload a new channel logo

Client Resources

A channel has various resources and settings:

• Name - Channel display name
• Subdomain - Custom subdomain for accessing content
• Logo - Channel branding image
• Connections - Integrations with external platforms
• Usage - Resource consumption metrics

Get channel details

Channels are referenced as [Client REF or Client Subdomain]

Get public available channel details

URL : /client/[Client REF or Client Subdomain]

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "client_id": 1,
    "client_name": "My Company Name",
    "client_ref": "abc123",
    "client_subdomain": "mycompanyname"
},

Global authentication

{
    "client_name": "My Company Name",
    "client_ref": "abc123",
    "client_subdomain": "mycompanyname"
}

Get channel logo image

Gets the image of the set channel logo

URL : /client/[Client REF or Client Subdomain]/image

Method : GET

Parameters

• BOOL light (Set to true to retrieve light version of channel logo)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": {
        "signed_url": "https://liveplatform-bucket-1.s3.eu-central-1.amazonaws.com/images/17000445481061980967.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEHYaDGV1LWNlbnRyYWwtMSJGMEQCIBljEZnZM%2BLN%2BBtHrfsZm3wpp2FKhwzb79gvimwdPZFfAiAdyCqFuJMTXhM0WniVEgTrLJKbrcv0ci2NgFce0J0pqSrOBQi%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDY5NjU4ODQzNTM2MSIMWVj%2BmP2fxY0r4yFuKqIFN1y4PCU3AEmnKPZJEqgfrYL0ytXjHUfhgpxIXMydphA8SeHsH9%2FLyVZglP4Wzcu6A0hmdmrixRfjosCdc2WaDbiem0hfzrOzVNDPx8be8r03doGb4q21E3ftrlmu2u6AJu5LfE53NS7ptIlxBXw%2BI7CyZ5P8qj9a4jgCbOmuu844hEh9wB9OE%2BszNQbfAheMrQZd20elk0Og90ZuzUv7cZ4jpf0IMLqsnsdOBCOusa7cmiLugDYc2YhZpZNgw274HdAE9G4RlDoeJ7TaVLiwAytLbPrfsU6lcsgkhhqdOnU7eK5YFMMa4TIj%2FsdjuKt5XwxXN1NtZ0oZjLckznPxQfYw5B92NscngloP3DQKCKemBSDbE1jDdLyq%2FwwWPMD2a9C%2Bf9LIJbgDOl%2B10yVuVcwN5SWXlaL%2FC9WLjUzz2QdkNu4D5r6VNNDqEu1qLX%2Ff6cWQG1b5vNuJLRK3hYVNJyukMYoGcxiGVbNEESsSnQg5ACAJVHHvAFIGaY8YEG9UGw41m5P1oZGF4FD0KipUSQDyZy8OYNhuUETLKZTw7L%2FHLldYHUcdhJfnAAOFRg9NbOB5CiVmHLbQhPeXTVpK3ObiIQ%2F3IchuU1P%2B7CX1hApcLTpMLETSFCpOoL%2FHzPiuAHKPLP12RrYYLUZQI48OrgajyG5d4Yz7KveMNdm6sQj%2BhxlK1095JlbUUFBNTjBoKS77bb2Omh6Rz6k6ryWboM%2B1wM%2FPYF5Zjmqo9zmdISCehHDU1mD1JqyZNTyV6OunmbcS%2FwcfN0j75GHQMyWgsJpKqyyowawsloagwGjaoDo1YTPxwuyRWYuXjEYbJlP52oCvmvreUy3dbGudKM2rzWhRhZg7FlVKqqdBmXJLwdsafEYMNN%2BCx31XarT5nocwO8Mw0PbiqgY6sgGEEJiVtKxz5QFljeFak0eoqLQOnA2zw4NzbklgAe%2BCrbMoMuxgwoxZ2whlccOMB%2BB%2FgBIwjHkUGZDu%2BNxYpoWzRvT6FN1dR4u2x79gPaiff7d5riaCDO6S792AxJ%2Fjiq7Mn8K7OfNvlU%2BjvfsNrfnGEaZjY3U4qwZgto9QthM%2FtGZ2%2B4DY9PGFKE6WefN670aiJqX%2FFb0YWDK6wtxPuxe1VZ%2F9yf9KF1fk5DWcL0NWdEy4&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA2EL7H76QSGUDAQTQ%2F20231118%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20231118T141244Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Signature=d7896553f15ad87627bea980b7f0268b60f9c4c6e4c95553c7164e9f2e578bd8"
    },
    "status": 200
}

Notes

• The signed url is a temporary url which is only valid for up to 20 minutes, to use the link for longer request a new one

Upload client logo image

Uploads an image for the logo of the given client

URL : /client/[CLIENT REF or CLIENT SUBDOMAIN]/image

Method : POST

Parameters

• STRING filename (required)

Authentication required : YES

Success Response

Code : 201 Created

Global authentication & User API key

{
    "asset_ref": "ABCD1234",
    "upload_url": "https://liveplatform-bucket-1.s3.eu-central-1.amazonaws.com/images/17000445481061980967.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEHYaDGV1LWNlbnRyYWwtMSJGMEQCIBljEZnZM%2BLN%2BBtHrfsZm3wpp2FKhwzb79gvimwdPZFfAiAdyCqFuJMTXhM0WniVEgTrLJKbrcv0ci2NgFce0J0pqSrOBQi%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAEaDDY5NjU4ODQzNTM2MSIMWVj%2BmP2fxY0r4yFuKqIFN1y4PCU3AEmnKPZJEqgfrYL0ytXjHUfhgpxIXMydphA8SeHsH9%2FLyVZglP4Wzcu6A0hmdmrixRfjosCdc2WaDbiem0hfzrOzVNDPx8be8r03doGb4q21E3ftrlmu2u6AJu5LfE53NS7ptIlxBXw%2BI7CyZ5P8qj9a4jgCbOmuu844hEh9wB9OE%2BszNQbfAheMrQZd20elk0Og90ZuzUv7cZ4jpf0IMLqsnsdOBCOusa7cmiLugDYc2YhZpZNgw274HdAE9G4RlDoeJ7TaVLiwAytLbPrfsU6lcsgkhhqdOnU7eK5YFMMa4TIj%2FsdjuKt5XwxXN1NtZ0oZjLckznPxQfYw5B92NscngloP3DQKCKemBSDbE1jDdLyq%2FwwWPMD2a9C%2Bf9LIJbgDOl%2B10yVuVcwN5SWXlaL%2FC9WLjUzz2QdkNu4D5r6VNNDqEu1qLX%2Ff6cWQG1b5vNuJLRK3hYVNJyukMYoGcxiGVbNEESsSnQg5ACAJVHHvAFIGaY8YEG9UGw41m5P1oZGF4FD0KipUSQDyZy8OYNhuUETLKZTw7L%2FHLldYHUcdhJfnAAOFRg9NbOB5CiVmHLbQhPeXTVpK3ObiIQ%2F3IchuU1P%2B7CX1hApcLTpMLETSFCpOoL%2FHzPiuAHKPLP12RrYYLUZQI48OrgajyG5d4Yz7KveMNdm6sQj%2BhxlK1095JlbUUFBNTjBoKS77bb2Omh6Rz6k6ryWboM%2B1wM%2FPYF5Zjmqo9zmdISCehHDU1mD1JqyZNTyV6OunmbcS%2FwcfN0j75GHQMyWgsJpKqyyowawsloagwGjaoDo1YTPxwuyRWYuXjEYbJlP52oCvmvreUy3dbGudKM2rzWhRhZg7FlVKqqdBmXJLwdsafEYMNN%2BCx31XarT5nocwO8Mw0PbiqgY6sgGEEJiVtKxz5QFljeFak0eoqLQOnA2zw4NzbklgAe%2BCrbMoMuxgwoxZ2whlccOMB%2BB%2FgBIwjHkUGZDu%2BNxYpoWzRvT6FN1dR4u2x79gPaiff7d5riaCDO6S792AxJ%2Fjiq7Mn8K7OfNvlU%2BjvfsNrfnGEaZjY3U4qwZgto9QthM%2FtGZ2%2B4DY9PGFKE6WefN670aiJqX%2FFb0YWDK6wtxPuxe1VZ%2F9yf9KF1fk5DWcL0NWdEy4&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA2EL7H76QSGUDAQTQ%2F20231118%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20231118T141244Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1200&X-Amz-Signature=d7896553f15ad87627bea980b7f0268b60f9c4c6e4c95553c7164e9f2e578bd8"
}

Get usage for channel

Gets current estimated total usage for channel

URL : /client/[Client REF]/usage

Method : GET

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": {
        "currency": "eur",
        "total": 15.138370833333333,
        "types": {
            "delivery_total": {
                "cost": 0.2245375,
                "unit_cost": 0.002875,
                "usage": 78.1
            },
            "emails_total": {
                "cost": 0.171,
                "unit_cost": 0.003,
                "usage": 57
            },
            "encoding_total": {
                "cost": 14.626833333333334,
                "unit_cost": 0.095,
                "usage": 153.96666666666667
            },
            "ondemand_total": {
                "cost": 0.116,
                "unit_cost": 0.00725,
                "usage": 16
            }
        }
    },
    "status": 200
}

Get all connections

Get all user connections from channel

URL : /client/[CLIENT REF]/connections

Method : GET

Parameters

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)
• STRING search (Anything in title or description can be matched here)
• BOOL active (default true)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": [
        {
            "conn_ref": "UJBOHFzzTmN2tLFk5pv6QG22Rvby860R",
            "conn_user_ref": "E0QRGZ",
            "data": {
                "user_client_ref": "g5zp39",
                "user_email": "invoice@beestreamed.com",
                "user_first": "Bee",
                "user_last": "Streamed",
                "user_ref": "E0QRGZ"
            },
            "row_num": 1
        },
        {
            "conn_ref": "2smi2o66ifupm0wgc3p88gc7l81k3bho",
            "conn_user_ref": "we3b2e3mtu7r",
            "data": {
                "user_client_ref": "g5zp39",
                "user_email": "frederik.larsenbang@gmail.com",
                "user_first": "Frederik",
                "user_last": "Bang",
                "user_ref": "we3b2e3mtu7r"
            },
            "row_num": 2
        }
    ],
    "status": 200
}

Create channel connection

Accept a channel connection

URL : /client/[Client REF]/connections

Method : POST

Parameters

• STRING email (required)

Authentication required : YES

Success Response

Code : 200 OK

User Session key

{
    "message": "Connection accepted!",
    "status": 200
}

Delete user connection

Delete user connection

URL : /client/[CLIENT REF]/connections

Method : delete

Parameters

• STRING connref (required)

Authentication required : YES

Success Response

Code : 200 OK

User Session key

{
    "message": "Connection deleted!",
    "status": 200
}

Introduction

The User API allows you to manage user accounts and preferences. This introduction will help you understand the available endpoints and concepts for user management.

Available Endpoints

• Get User Details - Retrieve information about the authenticated user
• Create User - Register a new user account
• Update User - Modify user information

User Resources

• Update Email - Change user email address

User Management

The User API provides endpoints for managing user accounts, including:

• Retrieving user profile information
• Updating user details
• Managing email preferences
• Accessing user-specific settings

Authentication

All User API endpoints require authentication with a valid access token. User operations are restricted to the authenticated user's own account.

Data Privacy

User data is handled according to our privacy policy. Personal information is protected and only accessible to the authenticated user or authorized administrators.

Delete organization connection

Delete organization connection

URL : /user/[SESSION KEY]/connections

Method : delete

Parameters

• STRING connref (required)

Authentication required : YES

Success Response

Code : 200 OK

User Session key

{
    "message": "Connection deleted!",
    "status": 200
}

Get all connections

Get all organization connections from user

URL : /user/[SESSION REF]/connections

Method : GET

Parameters

• INT maxResults (default 10)
• INT page (default 1)
• INT indexStart (default latest entry)
• STRING search (Anything in title or description can be matched here)
• BOOL active (default true)

Authentication required : YES

Success Response

Code : 200 OK

User API key

{
    "data": [
        {
            "conn_client_ref": "Ki0hne",
            "conn_ref": "ANQSPe2oU51U5lR3UVvBJNiak7W6pmwS",
            "data": {
                "client_logo": "ol9vozodapjfo6et",
                "client_logo_light": "8hlmoubhw4h9oc3q",
                "client_name": "Experian",
                "client_ref": "Ki0hne",
                "client_subdomain": "experian"
            },
            "row_num": 1
        },
        {
            "conn_client_ref": "g5zp39",
            "conn_ref": "UJBOHFzzTmN2tLFk5pv6QG22Rvby860R",
            "current": true,
            "data": {
                "client_logo": "5b8mpgkaocs5wb4v",
                "client_logo_light": "y17li9bemabtzto0",
                "client_name": "TestOrg",
                "client_ref": "g5zp39",
                "client_subdomain": "testorg"
            },
            "row_num": 2
        }
    ],
    "status": 200
}

Notes

• This only works using a user unique session key.

Accept organization connection

Accept an organization connection

URL : /user/[SESSION KEY]/connections

Method : POST

Parameters

• STRING connref (required)

Authentication required : YES

Success Response

Code : 200 OK

User Session key

{
    "message": "Connection accepted!",
    "status": 200
}