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 required string
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 string
Unique identifier for the object.
event_details object
Configure additional features on a broadcast.
chat object
Toggle the chat functionality. Viewers must set a nickname to send messages. The chat can be moderated from the Dashboard.
enable bool
multi_camera object
enable bool
streams strings
An array of streams the viewers can switch between.
questions object
Let viewers send in questions that an administrator can answer in the Dashboard or answer the question directly in the broadcast.
enable bool
radio object
Let the viewers switch to a audio-only stream when watching the broadcast.
enable bool
scorebar object
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 bool
shopping object
enable bool
products strings
An array of products to display during the broadcast
fqdn string
stream_id string
The ID of the broadcasts stream.
images array

The broadcasts poster images. The first image in the array is the primary image. An image is loaded using the public image endpoint, where the filename is the last argument.

The image endpoint allows for on-demand resizing of the requested images. It is possible to select to scale by height or by width.

Scale by height: https://{fqdn}/images/h/{size}/{image}

Scale by width: https://{fqdn}/images/w/{size}/{image}

metadata object
title string
description string
duration string
The duration of the broadcast, set when the broadcast has transitioned to complete
orientation string

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 object
Sport metadata is used when enabling the event_details.scorebar setting.
away_team_name string
away_team_score string
home_team_name string
home_team_score string
playing_period string
type string
scheduled_start_time datetime
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 datetime
Currently not in use.
actual_start_time datetime
The time the broadcast went live. Empty until the broadcast transitions to the live state.
actual_end_time datetime
The time the broadcast was completed. Empty until the broadcast transitions to the completed state.
private bool
A private broadcast is not included in public API responses and will not appear on the Play page.
protected object
status object
life_cycle_status string
Describes where a broadcast is in its life cycle. See the status table in the Life cycle status section above for possible values.
stream Stream
More attributes
account_id number
created_at string
url string

Create a broadcast

Schedules a new broadcast

Parameters

scheduled_start_time required datetime
The broadcast will go live at the provided scheduled start time. Expected to be in UTC and formatted according to ISO 8601
stream_id optional string
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 required object
Set metadata for the broadcast like title and description.
description optional string
title required string
orientation optional string

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 optional object
Sport metadata is used when enabling the event_details.scorebar setting.
away_team_name optional string
away_team_score optional string
home_team_name optional string
home_team_score optional string
playing_period optional string
type optional string
event_details optional object
Configure additional features on a broadcast.
chat optional object
Toggle the chat functionality. Viewers must set a nickname to send messages. The chat can be moderated from the Dashboard.
enable optional bool
multi_camera optional object
enable optional bool
streams optional strings
An array of streams the viwers can switch between.
questions optional object
Let viewers send in questions that an administrator can answer in the Dashboard or answer the question directly in the broadcast.
enable optional bool
radio optional object
Let the viewers switch to a audio-only stream when watching the broadcast.
enable optional bool
scorebar optional object
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 optional bool
shopping optional object
enable optional bool
products optional strings
An array of products to display during the broadcast
private optional bool
A private broadcast is not included in public API responses and will not appear on the Play page.
protected optional object
Content protection settings for the broadcast, like enabling pay per view.
pay_per_view optional object
enabled optional bool
Indicates if the broadcast has pay per view enabled
products optional strings
A list of products providing access to the broadcast. See Products for more information about modifying content access.
tags optional strings
Tags can be used to connect a broadcast with collections
assigned_to optional number

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 optional string
Filters broadcasts based on the type. Possible values are all, past, or upcoming
stream_id optional string
Filters the list on broadcast with the stream id. It’s not possible to filter on ephemeral streams.
More parameters
direction optional string
page optional string
per_page optional string
sort optional string

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

Retrieve analytics for a broadcast

The endpoint returns data for the specified time period.

Parameters

content required string
ID of the broadcast or video.
start optional string
Start date, default is 15 days from the current date.
end optional string
End date, default is todays date.

Returns

A analytics response.

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 required string
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 required string
Available events are product.hide and product.show
id required string
ID of the product the event applies to

Update a broadcast

Updates an existing broadcast

Parameters

event_details optional object
Configure additional features on a broadcast.
chat optional object
Toggle the chat functionality. Viewers must set a nickname to send messages. The chat can be moderated from the Dashboard.
enable optional bool
multi_camera optional object
enable optional bool
streams optional strings
An array of streams the viwers can switch between.
questions optional object
Let viewers send in questions that an administrator can answer in the Dashboard or answer the question directly in the broadcast.
enable optional bool
radio optional object
Let the viewers switch to a audio-only stream when watching the broadcast.
enable optional bool
scorebar optional object
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 optional bool
shopping optional object
enable optional bool
products optional strings
An array of products to display during the broadcast
private optional bool
A private broadcast is not included in public API responses and will not appear on the Play page.
protected optional object
Content protection settings for the broadcast, like enabling pay per view.
pay_per_view optional object
enabled optional bool
Indicates if the broadcast has pay per view enabled
products optional strings
A list of products providing access to the broadcast. See Products for more information about modifying content access.
images optional array
Images to use as poster for the broadcast. Expects filenames of previously uploaded images.
metadata optional object
Set metadata for the broadcast like title and description.
title optional string
description optional string
orientation optional string

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 optional object
Sport metadata is used when enabling the event_details.scorebar setting.
away_team_name optional string
away_team_score optional string
home_team_name optional string
home_team_score optional string
playing_period optional string
type optional string
scheduled_start_time optional datetime

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 optional string
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.
tags optional strings
Tags can be used to connect a broadcast with collections
assigned_to optional number

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 bool
Disables the Play site.
metadata object
title string
about string
footer string
email string
phone string
website_url string
collections object
name object
singular string
plural string
default object
archive object
disabled bool
past object
disabled bool
upcoming object
disabled bool
donation object
enabled bool
amounts numbers
currency string
translations object
button hash
message hash
thanks hash
images object
background string
logotype string
player object
display object
custom_css string
published_date string
title string
tags string
exclude_tags string
information_message object
message string
support object
help_button object
disabled bool
More attributes
fqdn string
organization_identifer string
resources string
seo object
updated string

Update the Play site

Update the play sites configuration

Parameters

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

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 string
Unique identifier for the object.
access object
Defines what access a product provides. Access can not be set for products of type good.
expires_after string
Expiration expressed as a duration. Defaults to 48h
expires_at string
Expiration expressed as a fixed date. Access is provided to 23:59:59 of the provided date.
content string
organization bool
To grant access to content on other accounts in an organisation.
single_access bool
To grant access to one or more content.
active bool
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 strings

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

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 string
Unique identifier for the object.
account_id string
metadata string
cdn string
status string
health_status string
More attributes
created_at string
updated_at string
url string

Create a stream

Parameters

metadata required object
title required string
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 optional string
cdn optional object
format optional string
The format parameter isn’t currently used.
region optional string

Geographical region for this streams ingestion servers.

Available regions:

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

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 optional string
page optional string
per_page optional string
sort optional string

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 required string
Date and time the data should be loaded from
to required string
Date and time the data should be loaded to

Returns

A stream health object.

Update a stream

Updates a stream

Parameters

metadata optional object
title optional string
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 optional string
cdn optional object
format optional string
The format parameter isn’t currently used.
region optional string

Geographical region for this streams ingestion servers.

Available regions:

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

Returns

A updated stream object.

Live shopping Product

Add live shopping 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.

Create live shopping products

Creates broadcast products and attaches them to the provided broadcast

Parameters

product_id required strings
The product id in your system
title required strings
The title of your product
description optional strings
Your product description
price required integer 
For example:
32.50 translates to 3250
100 translates to 10000
image_url required strings
The full url to your product image
currency optional strings
The default currency of the product, defaults to SEK
url required strings
The full url to your product
variants optional object
variant_id required strings
The product variant id in your system
title required strings
The title of your product
price required integer 
The price of the product variant in centesimal format.
For example:
32.50 is translated to 3250
100 is translated to 10000
image_url optional strings
The full url to your product variant image

Delete live shopping products

Deletes broadcast products from the given broadcast

Parameters

id required array
An array of ids to remove

List live shopping products

Retrieves broadcast products for the given broadcast

Parameters

No parameters

Returns

The products on the broadcast.

Sort live shopping products

Sorts a the products based on the order of the passed ids

Parameters

id required array
An array of ids to sort

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.

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" button-text="A Live Shopping event"></streamify-liveshopping>

The HTML element takes the following arguments.

  • id (required)
  • autostart-if-live (boolean, default: false)
    • Opens minified player if broadcast is live
  • 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.
  • ga (boolean, default: false)
    • Enable Google Analytics integration
  • hide (boolean, default: false)
  • hide-button (boolean, default: false)
  • hide-calendar (boolean, default: false)
  • hide-title (boolean, default: false)
  • info-button (boolean, default: true)
    • Display a info button if the broadcast has a description.
  • persistent (boolean, default: false)
    • The player is persited as a mini-player on the site as the user navigates between pages. This do not work on Shopify shops.
  • play-button (boolean, default: false)
  • orientation (string, landscape/portrait, default: portrait)

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, which is described in the Event payload section. See the list below for available events.

The cart events must be configured on the Live Shopping setting page before they are dispatched by the player. The player events are always dispatched without configuration.

Event Callback
cart.add A product was added to the players cart Yes
cart.update The quantity was changed Yes
cart.remove The product was removed from the cart, or quantity was changed to 0. Yes
cart.checkout The user clicked on the Go to checkout button
player.open The player was opened
player.minimize The player was minimized
player.close The player was closed
player.update Dispatched for each product added to the broadcast, see the product hydration section
player.metrics Can be used to implement custom analytics solutions, see custom analytics section

Event payload

The event payload contains up to two arguments, the product data and sometimes a callback. Both are described here below. Refer to the code examples to the right for implementing the events in your code.

Product data

The cart events contains a product object describing the product. The object varies slightly between the cart events. The product object is provided as the first argument for the event.
sku SKU of the product
quantity Number of products to add to the cart, always 1 for the cart.add event.
lineId A custom line ID set in the callback during cart.add, it is included in the cart.update and cart.remove events.
parentId The ID of the parent product to an SKU, not always set.

Callback

Some events require a callback to let the player know if the action succeeded. The callback is provided as the second argument for the event.

Property Optional
success Set to true if the event was successful or false if it failed. No
reason A reason if the action failed, for example, the product was out of stock for which we provide the predefined value out-of-stock. Other errors should be in human readable strings Yes
lineId A line ID provided by your shopping cart after a product was added to the cart. Yes

Executing the callback is required for the player to function correctly.

callback({
    success: true,
    reason: '',
    lineId: '1234',
});

Product Hydration

The Floating Players API allows updating the information displayed for products in a broadcast. This means that you can change details like the price or language of a product added to the broadcast.

You can achieve this by adding an event listener to the player for the product.update event, which will fire for each product in the broadcast, allowing you to load new data from your backend and update the product information accordingly.

Google Analytics

The players' Google Analytics integration lets you measure interactions by sending events to your Google Analytics account.

Adding the ga attribute to the player’s embed code tells the player to send events using the Google Analytics gtag.js API.

<streamify-liveshopping ga="true" id="id-of-broadcast"></streamify-liveshopping>

Prerequisites

You must be on the Professional plan or higher to enable the integration.

Event payload

Event name format: liveshopping_{event} Parameters always included:

broadcast_name
broadcast_id 
live:          true/false
time_seconds:  21
Available event
liveshopping_page_view Dispatched when the player is opened to record a view.
liveshopping_playback Playback related events.
liveshopping_interaction Event for all user interactions with the player.
liveshopping_add_to_cart
liveshopping_remove_from_cart
liveshopping_go_to_checkout User went to checkout, include all items in the cart in the event data.
liveshopping_view_cart User viewed the cart (in the player), include all items in the cart in the event data.
liveshopping_jump_to_item User used the button to jump to the product in the broadcast.
liveshopping_view_item User was exposed to the overlayed product.
liveshopping_select_item User clicked on product in the product list.

Playback parameters

"broadcast_name"
"broadcast_id"
"live":         true/false
"time_seconds": 21
"type":         "muted"
Types muted, close, pause, play, resume, seek, unmuted`

Interaction parameters

"broadcast_name"
"broadcast_id"
"live":          true/false
"time_seconds":  21
"type":          "reaction" / "message"
"count":         "2" // included for reactions.
Types reation, message, add_to_calendar

Product parameters

All product related event share the same parameters:

"broadcast_name"
"broadcast_id"
"live":         true/false
"time_seconds": 21
"currency":     "sek"
"value":        100
"items": [
	{
		"item_id": "SKU_1234"
		"item_name": "Some product"
		"price": 100
		"discount": 20 // if we know it 
		"quanitity": 1,
	}
]

Custom Analytics

You can implement custom analytics solutions by listening to the event player.metrics. There are 3 main categories of events described below: playback, interaction, and shopping.

Event payload

The player.metrics event payload contains a parameters object with a few properties that exists for all event types.

  • broadcast_id - The broadcasts ID
  • broadcast_name - Name of the broadcast
  • live - Indicates if the broadcast is live or recorded
  • time_seconds - How many seconds in the broadcast the event occoured.
{
  "event": EVENT,
  "parameters": {
    "broadcast_id": "xxxx",
    "broadcast_name": "My broadcast",
    "live": true,
    "time_seconds": "0.00",
  }
}

Playback

These events can be dispatched during playback.

Event
close The player was closed
minimize The player was minimized
muted The player was muted
normalize The player was restored from the minimized state
page_view Dispatched when the player has been opened
pause Playback has been paused.
ping Sent every 60 seconds when the player is opened
play Playback has begun
resume Playback has resumed
seek The viewer sought in the video
unmuted The player was unmuted

Interaction

Interaction events are differentiated by a type property in the parameters object.

Event
interaction The viewer sent a message, liked, or any of the other supported interactions
Parameters
type The type of interaction: message, reaction, or add_to_calendar
calendar Present when type is add_to_calendar
count Present when type is reaction, indicates number of reactions sent

Shopping

Event
add_to_cart Item was added to the cart
remove_from_cart Item was removed from the cart
begin_checkout User went to checkout, includes all items in the cart in the event data.
view_cart User viewed the cart (in the player), includes all items in the cart in the event data.
jump_to_item User used the button to jump to the product in the broadcast.
select_item User clicked on product in the product list.
view_item User was exposed to the overlayed product.
Parameters
currency Currency used for the items price
value Total value of items in the event
items Array of items, contains all items added to the cart for the begin_checkout and view_cart events.
items.item_id Itme SKU
items.item_name Item name
items.price Price of item
items.quantity Quanitity of item

Shopify

Shopify support is included in the player out of the box, no extra code is needed for the integration.