Platform API (3.0.0)

Download OpenAPI specification:Download

Introduction

This API allows integration of your backend (like content management or publishing systems) with the Flowplayer platform for managing video and livestream assets. It can be used to fetch, list, create, update and delete Livestreams, Live Sources, Playlists, Categories and Videos.

Authentication

All API requests need to be authenticated by providing the API keys as an header, x-flowplayer-api-key.

Requesting the API

Base url for the API is:

  https://api.flowplayer.com/platform/v3/

Endpoint structure

Each asset type has its own path and endpoint in the API with the following structure:

Asset type Path
Livestreams /livestreams
Live Sources /livesources
Playlists /playlists
Category /categories
Video /videos

Content type

This API only supports JSON-format output.

Sample request

A sample request for listing livestreams using the API.

  curl https://api.flowplayer.com/platform/v3/livestreams \
  -H "x-flowplayer-api-key: {my-api-key}" \
  -H "Content-Type: application/json"

Livestream

Go live now, schedule for later or start an 24x7 broadcast. The API supports creating, editing and deleting all supported types of livestreams, running from the Flowplayer platform as well as remote sources.

Scheduling type

When working with livestreams you need to define the type of livestream you want to use. We support two different types:

Type Description
scheduled Should be used if the livestream should start in the future or right away and have a defined end time. The typical use case would be an planned event, for example a soccer game.
linear Should be used when creating a 24x7 linear channel. Linear broadcasts come with some limitations, for example it's not possible to record them.

The different types are treated differently by our platform and after creation it's not possible to change type, so it's important that the correct type is selected.

Remote or not

We always recommend to create livestreams using our optimized encoding and delivery infrastructure. However, sometimes you may need a different approach for example if you get to use a stream from a different content provider. In this case creating a REMOTE livestream is the correct approach in order to ensure that you will get fully benefit from our features like analytics, even though the stream itself comes from a different provider.

You'll need to set the remote: true parameter and specify a stream.viewing_url to configure a REMOTE livestream correctly.

List Livestreams

Endpoint for fetching metadata about Livestreams on a specific Workspace.

Authorizations:
query Parameters
page
integer <int32>
Default: 1

Page number

page_size
integer <int32>
Default: 20

Page size

q
string
Example: q=foo%3Aname%2Ccustom_fields

Searches multiple text fields case insensitive and partial (don't require full matches).

For Livestreams it searches name, description, tags and custom_fields, wherecustom_fields searches all your different custom fields for matches. To limit the search to specific fields you can use colon (:) to specify fields. If you have multiple search terms you can use pipe (|) to separate the search terms.

Some examples:

Query Description
q=foo Searches all fields for foo.
q=foo:name,description Searches name and description fields for foo.
q=foo:name|bar:tags Searches name for foo and tags for bar. A Livestream must match both to be included.
live_source
string
Example: live_source=live_source_id_1

Returns all Livestreams that are connected to the specified Live source.

categories
string
Example: categories=category_id_1%2Ccategory_id_2

Will return Livestreams belonging to one of the specified Categories. Input should be a comma separated string with Category ids.

updated_at
string
Example: updated_at=24%3Ahours

Filter the response based on when the Livestream was updated. The filter can be specified in following formats:

Spec Description
YYYY-MM-DD'T'HH:mm:ss Returns all assets from updated after the specified date
YYYY-MM-DD,YYYY-MM-DD Returns all assets updated within the timespan
XX:hours Returns all assets which updated in the last XX hours
XX:days Returns all assets which updated in the last XX days
XX:weeks Returns all assets which updated in the last XX weeks
XX:months Returns all assets which updated in the last XX months
created_at
string
Example: created_at=2020-01-01%2C2020-02-01

Filter the response based on when the livestream was created. The filter can be specified in following formats:

Spec Description
YYYY-MM-DD'T'HH:mm:ss Returns all assets created after the specified date
YYYY-MM-DD,YYYY-MM-DD Returns all assets created within the given timespan
XX:hours Returns all assets created in the last XX hours
XX:days Returns all assets created in the last XX days
XX:weeks Returns all assets created in the last XX weeks
XX:months Returns all assets created in the last XX months
start_time
string
Example: start_time=1%3Adays

Filter the response based on the Livestream's start time. The filter can be specified in following formats:

Spec Description
YYYY-MM-DD'T'HH:mm:ss Returns all assets with start time after the specified date
YYYY-MM-DD,YYYY-MM-DD Returns all assets with start time within the timespan
XX:hours Returns all assets with start time in the last XX hours
XX:days Returns all assets with start time in the last XX days
XX:weeks Returns all assets with start time the last XX weeks
XX:months Returns all assets with start time in the last XX months
stop_time
string
Example: stop_time=2019-11-20T14

Filter the response based on when the Livestream's end time. The filter can be specified in following formats:

Spec Description
YYYY-MM-DD'T'HH:mm:ss Returns all assets with a stop time after the specified date
YYYY-MM-DD,YYYY-MM-DD Returns all assets with a stop time within the timespan
XX:hours Returns all assets with a stop time in the last XX hours
XX:days Returns all assets with a stop time in the last XX days
XX:weeks Returns all assets with a stop time the last XX weeks
XX:months Returns all assets with a stop time in the last XX months
sort_order
string
Default: "DESC"
Enum: "DESC" "ASC"
Example: sort_order=DESC
sort_by
string
Default: "name"
Enum: "created_at" "name" "start_time" "stop_time"
Example: sort_by=created_at

Responses

200

OK

401

Could not authenticate the request

404

The workspace was not found

get /livestreams
https://api.flowplayer.com/platform/v3/livestreams

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "page": 0,
  • "page_size": 20,
  • "total_count": 100,
  • "total_count_in_search": 5,
  • "total_pages": 4,
  • "assets":
    [
    ]
}

Create Livestream

Endpoint for creating one single Livestream.

Authorizations:
Request Body schema: application/json
name
required
string

The livestreams name, can be displayed in the player.

description
string

The livestreams description, can be displayed in the player.

start_time
string <date-time>

The start time for the Livestream formatted in yyyy-MM-dd'T'HH:mm:ssZ. Before the start time the Livestream will not be publically visible when delivered with platform embeds. Instead a count down will be displayed in the player.

The start time will also initiate recording if the Livestream has the recording option set to true.

stop_time
string <date-time>

The stop time for the Livestream formatted in yyyy-MM-dd'T'HH:mm:ssZ. Does not have any effect for the playback in the player; an ongoing Livestream will continue to play although the stoptime has passed.

The stop time is also when you recording will stop if the Livestream has the recording option set to true.

user_id
string

Id for the creator of the Livestream

remote
boolean

When set to true the Livestream is treated as a remote asset by the platform

ad_keywords
string

Used for replacing the ad_keywords macro in the VAST tag in any player that plays the Livestream. Find more information here.

no_ads
boolean

When set to true no ads will be displayed during this Livestream. Notice This feature only works from Iframe embeds.

published
boolean

If true this Livestream will be visible in public listings such as an MRSS-feed.

tags
string

A commaseperated list of tags.

category_id
string

Unique identifier for the Category the Livestream belongs to.

record
object

Contains recording settings for the Livestream

video
object

Contains settings for the Video that can be use to replace the Livestream in the player without re-embedding.

stream
object

Contains information about how to connect to our livestreaming servers and view the Livestream.

live_source
object

If defined, not null, the Live Source that is used for this livestream.

custom_fields
Array of objects
image_input
string

Url to an image file which will be downloaded and imported to the platform, to be used as poster image for the livestream. If the livestream is of remote type the image will not be downloaded and instead served from the provided URL.

workspace
object

site/workspace-object that is the owner of the Livestream

Responses

200

OK

400

Could not parse input body

401

Could not authenticate the request

404

At least one of the entities in the body was not found

422

Input validation failed

post /livestreams
https://api.flowplayer.com/platform/v3/livestreams

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Livestream name",
  • "description": "Livestream description",
  • "start_time": "2020-01-01T12:00:00.000Z",
  • "stop_time": "2020-01-01T13:00:00.000Z",
  • "user_id": "creator_of_livestream_id",
  • "remote": false,
  • "ad_keywords": "special_ads",
  • "no_ads": false,
  • "published": false,
  • "tags": "foo,bar",
  • "category_id": "example_category_id",
  • "record":
    {
    },
  • "video":
    {
    },
  • "stream":
    {},
  • "live_source":
    {
    },
  • "custom_fields":
    [
    ],
  • "workspace":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "livestream_id",
  • "name": "Livestream name",
  • "description": "Livestream description",
  • "start_time": "2020-01-01T12:00:00.000Z",
  • "stop_time": "2020-01-01T13:00:00.000Z",
  • "user_id": "creator_of_livestream_id",
  • "remote": false,
  • "ad_keywords": "special_ads",
  • "no_ads": false,
  • "published": false,
  • "tags": "foo,bar",
  • "category_id": "example_category_id",
  • "record":
    {
    },
  • "video":
    {
    },
  • "stream":
    {},
  • "live_source":
    {
    },
  • "custom_fields":
    [
    ],
  • "is_connected": false,
  • "created_at": "2020-01-01T12:33:22.000Z",
  • "updated_at": "2020-01-01T12:33:22.000Z",
  • "images":
    [],
  • "workspace":
    {
    }
}

Update Livestream

Endpoint for updating one single Livestream.

A sample request to activate recording of a Livestream using the API:

curl https://api.flowplayer.com/platform/v3/livestreams/{my-livestream-id} \
-H "x-flowplayer-api-key: {my-api-key}" \
-H "Content-Type: application/json" \
-X PUT -d '{ "record" : { "record" : true }}'
Authorizations:
path Parameters
id
required
string
Example: livestream_id

Unique identifier for the Livestream

Request Body schema: application/json
image_input
string

Url to an image file which will be downloaded and imported to the platform, to be used as poster image for the livestream. If the livestream is of remote type the image will not be downloaded and instead served from the provided URL.

The image will replace s previously specified poster image for the asset.

name
string

The livestreams name, can be displayed in the player.

description
string

The livestreams description, can be displayed in the player.

start_time
string <date-time>

The start time for the Livestream formatted in yyyy-MM-dd'T'HH:mm:ssZ. Before the start time the Livestream will not be publically visible when delivered with platform embeds. Instead a count down will be displayed in the player.

The start time will also initiate recording if the Livestream has the recording option set to true.

stop_time
string <date-time>

The stop time for the Livestream formatted in yyyy-MM-dd'T'HH:mm:ssZ. Does not have any effect for the playback in the player; an ongoing Livestream will continue to play although the stoptime has passed.

The stop time is also when you recording will stop if the Livestream has the recording option set to true.

user_id
string

Id for the creator of the Livestream

remote
boolean

When set to true the Livestream is treated as a remote asset by the platform

ad_keywords
string

Used for replacing the ad_keywords macro in the VAST tag in any player that plays the Livestream. Find more information here.

no_ads
boolean

When set to true no ads will be displayed during this Livestream. Notice This feature only works from Iframe embeds.

published
boolean

If true this Livestream will be visible in public listings such as an MRSS-feed.

tags
string

A commaseperated list of tags.

category_id
string

Unique identifier for the Category the Livestream belongs to.

record
object

Contains recording settings for the Livestream

video
object

Contains settings for the Video that can be use to replace the Livestream in the player without re-embedding.

stream
object

Contains information about how to connect to our livestreaming servers and view the Livestream.

live_source
object

If defined, not null, the Live Source that is used for this livestream.

custom_fields
Array of objects

Responses

200

OK

400

Could not parse input body

401

Could not authenticate the request

404

Either the livestream or at least one of other entities in the body was not found

422

Input validation failed

put /livestreams/{id}
https://api.flowplayer.com/platform/v3/livestreams/{id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Livestream name",
  • "description": "Livestream description",
  • "start_time": "2020-01-01T12:00:00.000Z",
  • "stop_time": "2020-01-01T13:00:00.000Z",
  • "user_id": "creator_of_livestream_id",
  • "remote": false,
  • "ad_keywords": "special_ads",
  • "no_ads": false,
  • "published": false,
  • "tags": "foo,bar",
  • "category_id": "example_category_id",
  • "record":
    {
    },
  • "video":
    {
    },
  • "stream":
    {},
  • "live_source":
    {
    },
  • "custom_fields":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "livestream_id",
  • "name": "Livestream name",
  • "description": "Livestream description",
  • "start_time": "2020-01-01T12:00:00.000Z",
  • "stop_time": "2020-01-01T13:00:00.000Z",
  • "user_id": "creator_of_livestream_id",
  • "remote": false,
  • "ad_keywords": "special_ads",
  • "no_ads": false,
  • "published": false,
  • "tags": "foo,bar",
  • "category_id": "example_category_id",
  • "record":
    {
    },
  • "video":
    {
    },
  • "stream":
    {},
  • "live_source":
    {
    },
  • "custom_fields":
    [
    ],
  • "is_connected": false,
  • "created_at": "2020-01-01T12:33:22.000Z",
  • "updated_at": "2020-01-01T12:33:22.000Z",
  • "images":
    [],
  • "workspace":
    {
    }
}

Get Livestream

Endpoint for fetching one single Livestream.

Authorizations:
path Parameters
id
required
string
Example: livestream_id

Unique identifier for the Livestream

Responses

200

OK

401

Could not authenticate the request

404

The Livestream was not found

get /livestreams/{id}
https://api.flowplayer.com/platform/v3/livestreams/{id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "livestream_id",
  • "name": "Livestream name",
  • "description": "Livestream description",
  • "start_time": "2020-01-01T12:00:00.000Z",
  • "stop_time": "2020-01-01T13:00:00.000Z",
  • "user_id": "creator_of_livestream_id",
  • <