Streamify API Reference

This reference describes the resources that make up the Streamify API.

The documentation is a work in progress. We add more documentation for our endpoints continually.

If you have any problems or requests please contact us at support@streamify.io

Authentication

The Streamify API uses API tokens to authenticate requests. You can create your API token by using the Authentication API as described below.

Requests made without an API token will return a 401 Unauthorized error. All API requests must be made over HTTPS. Requests made over HTTP will fail.

Authentication is performed using an Authorization header.

curl -H "Authorization: token <your-token>" https://api.streamify.io/user

You can also provide the API token as a URL query parameter for use cases where it is not possible to use a header:

curl https://api.streamify.io/user?access_token=TOKEN

Create a token

This endpoint expects a Basic Authentication header with the users' email and password.

Parameters

note
A brief note describing the token

Returns

Returns an API token if the credentials are valid. Use the returned token to authenticate subsequent API requests.

Revoke a token

Revokes the API token and the access provided by it.

Parameters

No parameters

Returns

An empty 200 OK

Errors

Streamify uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a resource was not found, etc.).

Codes in the 5xx range indicate an error with Streamifys servers.

200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API token provided or route doesn’t exist.
404 Not Found The requested resources does not exist

Timestamps

All timestamps are in ISO 8601 format and UTC: YYYY-MM-DDTHH:MM:SSZ

Broadcast

A broadcast object is used to perform a live broadcast. The broadcast is scheduled with a start time and bound to a live stream.

Life cycle status

The life cycle of a broadcast is described by the status.life_cycle_status property.

This, along with the stream.status attribute, allows you to build user interfaces that correctly reflects the state of a broadcast. The available statuses are listed below.

See the broadcast life cycle guide for more details.

abandoned This broadcast was never started.
complete The broadcast is finished.
created The broadcast has incomplete settings, so it is not ready to transition to a live or testing status, but it has been created and is otherwise valid.
error An error occoured on the broadcast.
live The broadcast is live.
liveStarting The broadcast is in the process of transitioning to live status.
liveStopping The broadcast is transitioning to complete.
ready The broadcast settings are complete and the broadcast can transition to a live or testing status.
revoked This broadcast was removed by an admin action.
testing The broadcast is only visible to the partner.
testStarting The broadcast is in the process of transitioning to testing status.

The broadcast object

Attributes
id
Unique identifier for the object.
event_details
Configure additional features on a broadcast.
chat
Toggle the chat functionality. Viewers must set a nickname to send messages. The chat can be moderated from the Dashboard.
enable
multi_camera
enable
streams
An array of streams the viewers can switch between.
questions
Let viewers send in questions that an administrator can answer in the Dashboard or answer the question directly in the broadcast.
enable
radio
Let the viewers switch to a audio-only stream when watching the broadcast.
enable
scorebar
Toggle a scorebar during sports broadcasts. It supports displaying team names and the current score. The metadata.sport attribute holds the presentation data for the scorebar.
enable
shopping
enable
products
An array of products to display during the broadcast
fqdn
stream_id
The ID of the broadcasts stream.
metadata
title
description
duration
The duration of the broadcast, set when the broadcast has transitioned to complete
orientation

Setting orientation instructs the broadcasting software only to send video in the given orientation. You can’t change this once a broadcast is live.

Allowed orientations:

  • landscape (default)
  • portrait
sport
Sport metadata is used when enabling the event_details.scorebar setting.
away_team_name
away_team_score
home_team_name
home_team_score
playing_period
type
scheduled_start_time
The broadcast will go live at this time. It must be no closer to the current time than 3 minutes to give backend services enough time to prepare the broadcasts transcoding.
scheduled_end_time
Currently not in use.
actual_start_time
The time the broadcast went live. Empty until the broadcast transitions to the live state.
actual_end_time
The time the broadcast was completed. Empty until the broadcast transitions to the completed state.
private
A private broadcast is not included in public API responses and will not appear on the Play page.
protected
status
life_cycle_status
Describes where a broadcast is in its life cycle. See the status table in the Life cycle status section above for possible values.
stream
More attributes
account_id
created_at
url

Add external product

Add products from Shopify or platforms supporting Google Merchant feeds to display them in the broadcast.

Requires that the integration with an e-commerce platform is in place.

Parameters

id
An array of product identifers, for example, the products Shopify ID.

Create a broadcast

Schedules a new broadcast

Parameters

scheduled_start_time
The broadcast will go live at the provided scheduled start time. Expected to be in UTC and formatted according to ISO 8601
stream_id
A stream to bind to this broadcast. An ephemeral stream is created if no stream is provided, this stream is removed when the broadcast has completed. Note: Please ensure to use unique streams if you are scheduling concurrent events.
metadata
Set metadata for the broadcast like title and description.
description
title
orientation

Setting orientation instructs the broadcasting software only to send video in the given orientation. You can’t change this once a broadcast is live.

Allowed orientations:

  • landscape (default)
  • portrait
sport
Sport metadata is used when enabling the event_details.scorebar setting.
away_team_name
away_team_score
home_team_name
home_team_score
playing_period
type
event_details
Configure additional features on a broadcast.
chat
Toggle the chat functionality. Viewers must set a nickname to send messages. The chat can be moderated from the Dashboard.
enable
multi_camera
enable
streams
An array of streams the viwers can switch between.
questions
Let viewers send in questions that an administrator can answer in the Dashboard or answer the question directly in the broadcast.
enable
radio
Let the viewers switch to a audio-only stream when watching the broadcast.
enable
scorebar
Toggle a scorebar during sports broadcasts. It supports displaying team names and the current score. The metadata.sport parameter holds the presentation data for the scorebar.
enable
shopping
enable
products
An array of products to display during the broadcast
private
A private broadcast is not included in public API responses and will not appear on the Play page.
protected
Content protection settings for the broadcast, like enabling pay per view.
pay_per_view
enabled
Indicates if the broadcast has pay per view enabled
products
A list of products providing access to the broadcast. See Products for more information about modifying content access.
tags
Tags can be used to connect a broadcast with collections
assigned_to

Returns

A broadcast scheduled to go live at the provided start time or an error

Delete a broadcast

Removes the broadcast.

Parameters

No parameters

Returns

An empty 200 OK.

Get broadcast count

Get the broadcast count for your account.

Parameters

No parameters

Returns

The number of broadcasts on the account.

List all broadcasts

List broadcasts. Can be filtered by type or stream

Parameters

type
Filters broadcasts based on the type. Possible values are all, past, or upcoming
stream
Filters the list on broadcast with the stream id. It’s not possible to filter on ephemeral streams.
More parameters
direction
page
per_page
sort

Returns

A paginated list of broadcasts or an empty list if no broadcasts were found.

Retrieve a broadcast

Parameters

No parameters

Returns

A broadcast object or a not found error

Stop a broadcast

A broadcast’s life cycle is controlled by transitioning the broadcast between states. Most state transitions are automatic but there is a handful that must be changed by an API call.

The transcoding stops after receiving the request and the broadcast transitions to completed moments after completed.

Periodically check the status of the broadcast by polling the get broadcast endpoint to ensure your user interface is updated correctly.

The endpoint returns an error if the broadcasts status.life_cycle_status property is not live or liveStarting.

Parameters

state
Valid state value is liveStopping

Returns

A broadcast object or an error

Trigger product events

Control how products are displayed during a broadcast by triggering product events

Parameters

event
Available events are product.hide and product.show
id
ID of the product the event applies to

Update a broadcast

Updates an existing broadcast

Parameters

scheduled_start_time

The broadcast will go live at the provided scheduled start time. Expected to be in UTC and formatted according to ISO 8601.

The scheduled start time can only be changed when the broadcast’s status.life_cycle_status is created or ready

stream_id
Change stream for this broadcast. You can not switch to an ephemeral stream when updating a broadcast. A live broadcast can’t be assigned a new stream.
metadata
Set metadata for the broadcast like title and description.
title
description
orientation

Setting orientation instructs the broadcasting software to only send video in the given orientation. This cannot be changed once a broadcast is live.

Allowed orientations:

  • landscape (default)
  • portrait
sport
Sport metadata is used when enabling the event_details.scorebar setting.
away_team_name
away_team_score
home_team_name
home_team_score
playing_period
type
event_details
Configure additional features on a broadcast.
chat
Toggle the chat functionality. Viewers must set a nickname to send messages. The chat can be moderated from the Dashboard.
enable
multi_camera
enable
streams
An array of streams the viwers can switch between.
questions
Let viewers send in questions that an administrator can answer in the Dashboard or answer the question directly in the broadcast.
enable
radio
Let the viewers switch to a audio-only stream when watching the broadcast.
enable
scorebar
Toggle a scorebar during sports broadcasts. It supports displaying team names and the current score. The metadata.sport parameter holds the presentation data for the scorebar.
enable
shopping
enable
products
An array of products to display during the broadcast
private
A private broadcast is not included in public API responses and will not appear on the Play page.
protected
Content protection settings for the broadcast, like enabling pay per view.
pay_per_view
enabled
Indicates if the broadcast has pay per view enabled
products
A list of products providing access to the broadcast. See Products for more information about modifying content access.
tags
Tags can be used to connect a broadcast with collections
assigned_to

Returns

The updated broadcast or an error

Play site

The Play Site support a few options which can be set using these endpoints.

The play site object

Attributes
disabled
Disables the Play site.
metadata
title
about
footer
email
phone
website_url
collections
name
singular
plural
default
archive
disabled
past
disabled
upcoming
disabled
donation
enabled
amounts
currency
translations
button
message
thanks
images
background
logotype
player
display
custom_css
published_date
title
tags
exclude_tags
information_message
message
support
help_button
disabled
More attributes
fqdn
organization_identifer
resources
seo
updated

Update the Play site

Update the play sites configuration

Parameters

disabled
Disables the Play site.
metadata
title
about
footer
email
phone
website_url
collections
name
singular
plural
default
archive
disabled
past
disabled
upcoming
disabled
donation
enabled
amounts
currency
translations
button
message
thanks
player
Configure the appearance of the player.
display
custom_css
Custom CSS are injected into the Play Site, allowing for greater customization.
published_date
Enable displaying the Publish date of a video
title
tags
exclude_tags
support
help_button
disabled
More parameters
organization_identifer
seo

Returns

The Play Site object

Product

The Product object represents a ticket for a broadcast, a physical product, or a digital service depending on the Products type.

Goods

Products can be added with the type Goods. A good can in addition to the standard title, description, and price also have inventory and package dimensions. The access field is not available.

Services

This can be a sponsorship, access to a VIP chat, or any other services the user or Streamify can make up.

The Access field is available for products of type service as access to a service can be time-limited.

The attributes array is used when a service product should give access to features on Play, for example, a VIP chat.

For example: "attributes": ["streamify.vip_chat"]

No attributes are needed for services our customer thinks up by themselves. Perhaps our customer wants to offer a Patreon type of membership or similar.

Note that we could add attributes that allow our customers to collect more information about the users during the payment process.

A supporter membership product with recurring billing where the user receives a t-shirt.

"attributes": ["streamify.collect_customer_shipping_info"]

Stream

Streams are a new type for our classic products. The end result of buying a stream-type product is a Ticket assigned to the customer’s Play user, which provides access to content. The access the product provides is decided by the properties of the Access field.

The product object

Attributes
id
Unique identifier for the object.
access
Defines what access a product provides. Access can not be set for products of type good.
expires_after
Expiration expressed as a duration. Defaults to 48h
expires_at
Expiration expressed as a fixed date. Access is provided to 23:59:59 of the provided date.
content
organization
To grant access to content on other accounts in an organisation.
single_access
To grant access to one or more content.
active
Allows a product to be deactivated but still be valid. Providing a way to work on products without them being published. Or the selling of a broadcast but unpublishing after the content should no longer be offered but still provide access for existing buyers. Default is false. The product must be activated before it can be used.
attributes

Attributes of the product.

A t-shirts attributes could be [“Color”, “Size”] or set of system attributes which alters the payment flow on Play.

For example [“streamify.select_organization_account”] makes the payment flow render a drop down of accounts to select from. Useful when buying a product that provides access to content from all accounts in a sports organisation and the buyer is given the option to select a favourite team to attribute the purchase to.

description
name
The name of the product is displayed to user when buying the product.
metadata
String key-value pairs. Limited to 10 key-value pairs. Key is max 40 chars and value 400 chars.
package_dimensions
price
images
Array of image URLs. A product can have 8 images. Supported file extensions: .png .jpg .jpeg
stock_keeping_unit
type
good, service, or stream
More attributes
account_id
created_at
updated_at

Stream

A stream is the ingestion point for your broadcast equipment or application. A stream can be connected to multiple broadcasts and reused, allowing you to configure the broadcast equipment once.

Creating a stream is necessary when using advanced functionality, for example, Multi-Camera Streaming.

See the Stream guide

The stream object

Attributes
id
Unique identifier for the object.
account_id
metadata
cdn
status
health_status
More attributes
created_at
updated_at
url

Create a stream

Parameters

metadata
title
A title for the stream. This is visible to the viewers if the stream is used as a part of a Multi-Camera broadcast.
description
cdn
format
The format parameter isn’t currently used.
region

Geographical region for this streams ingestion servers.

Available regions:

  • europe-north
  • europe-west (default)
  • australia-southeast
inheritance
Allows the stream to be inherited to connected accounts.
enable

Returns

A ready to use stream.

Delete a stream

Deletes a stream.

Parameters

No parameters

Returns

An empty 200 OK.

List all streams

List all streams, ephemeral streams can’t be listed.

Parameters

No parameters
More parameters
direction
page
per_page
sort

Returns

Returns a list of streams.

Retrieve a stream

Parameters

No parameters

Returns

A stream object or a not found error.

Stream health

Retrieve the stream’s health history for a specifed time period, usually the duration of a broadcast the stream was used with.

Parameters

from
Date and time the data should be loaded from
to
Date and time the data should be loaded to

Returns

A stream health object.

Update a stream

Updates a stream

Parameters

metadata
title
A title for the stream. This is visible to the viewers if the stream is used as a part of a Multi-Camera broadcast.
description
cdn
format
The format parameter isn’t currently used.
region

Geographical region for this streams ingestion servers.

Available regions:

  • europe-north
  • europe-west (default)
  • australia-southeast
inheritance
Allows the stream to be inherited to connected accounts.
enable

Returns

A updated stream object.

Event

The player dispatches events based on user interactions, for example, when a user clicks on the Add to cart button in the player. The event payload varies with the event type. See the list below for available events and the corresponding payloads.

addProduct Click on the Add to cart button
  • id - Id of the product/variation.
  • quantity - Number of products.
  • playerId - An id of the floating player if you want to send an event back when a product has been added to your cart.

Including

Include the Floating Player JS script on each page of your site. Preferable either inside <head></head> or at the bottom before </body>.

Always load the script from cdn.streamify.io, do not host it yourself.

Once this is done, you can use our custom-HTML-element to add a floating player anywhere on the website.

<streamify-liveshopping id="id-of-broadcast" size="portrait" button-text="Liveshopping with Pedro!"></streamify-liveshopping>

The HTML element takes up to three arguments.

  • id (required)
  • size (defaults to portrait)
    • portrait, landscape, square are the current banner formats we support right now
  • button-text (defaults to broadcast title if not set or used)
    • You can add text here if you want to customize the button text in the banner.

Introduction

Floating Player JS lets you display your live video shopping events on your site and integrate the video player with your platform’s cart and checkout functionality.

Shopify

We dispatch the addProduct event from the player when a user clicks on Add to cart. You need to listen to this event to add the product to your Shopify cart. We provide an example here below.

document.querySelector('streamify-liveshopping').addEventListener('addProduct', ({ detail: [productData] }) => {
    fetch('/cart/add.js', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ items: [{ id: productData.id, quantity: 1 }] }),
    }).then((response) => {
        // All went well! Emit an event so we can reset the button and variant
        dispatchEvent(new CustomEvent('sfProductAdded', {
            bubbles: true,
            detail: {
                success: true,
                playerId: productData.playerId,
            },
        }));
    }).catch((error) => {
        // Something went wrong, emit an event so we can display some
        // kind of error on the product in the player
        dispatchEvent(new CustomEvent('sfProductAdded', {
            bubbles: true,
            detail: {
                success: false,
                playerId: productData.playerId,
            },
        }));
    })
});

Streamify API Reference