openapi: 3.0.0
info:
title: Platform API
version: "3.0.0"
description: |
# 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.
# Rate limits
Every API request has a rate limit, applied per the organization the `x-flowplayer-api-key` is part of. This means that for the same organization there is a limited number of requests per second that can be done.
By default, every organization can perform 1 request/second of every API. Enterprise organizations can do up to 3 requests/second of every API.
If your organization triggers this rate limit, you'll receive the response status code `429 - Too Many Requests` with a response body `{ "message" : "Too Many Requests"}`.
# 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"
servers:
- url: https://api.flowplayer.com/platform/v3
security:
- api_key: [] # use the same name as under securitySchemes
id: [] # use the same name as under securitySchemes
paths:
/livestreams:
$ref: livestream.yaml#/components/paths/Livestream
/livestreams/{id}:
$ref: livestream.yaml#/components/paths/Livestream_Single
/livestreams/{id}/ovelays/{template_id}:
$ref: liveoverlay.yaml#/components/paths/LiveOverlay_Single
/livesources:
$ref: livesource.yaml#/components/paths/LiveSource
/livesources/{id}:
$ref: livesource.yaml#/components/paths/LiveSource_Single
/playlists:
$ref: playlist.yaml#/components/paths/Playlist
/playlists/{id}:
$ref: playlist.yaml#/components/paths/Playlist_Single
/categories:
$ref: category.yaml#/components/paths/Category
/categories/{id}:
$ref: category.yaml#/components/paths/Category_Single
/videos:
$ref: video.yaml#/components/paths/Video
/videos/{id}:
$ref: video.yaml#/components/paths/Video_Single
/videos/{id}/transcriptions:
$ref: transcription.yaml#/components/paths/Transcription
tags:
#- name: Playlist
# description: Playlists allow you to group videos into a sequential playback list. You can create `manual` playlists where you add and arrange the videos exactly as you want them, or `automatic` playlists where list content and order are updated automatically and continously based on a set of rules that you specify.
##- name: Video
## description: |
- name: Livestream
description: |
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. |
| simulive | Simulive can be used to simulate a livestream by defining a playlist of existing videos. The videos will be streamed as a livestream in the order specified in the playlist. |
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.
- name: Live Source
description: |
Live sources greatly simplifies livestreaming for those doing a lot of livestreaming and is a unique feature to Flowplayer.
#### What is live sources ####
A Live source is a fixed stream name which may be re-used for multiple broadcasts.
#### Why live sources ####
We invented the concept of live sources to simplify the process and reduce the errors in livestreaming setup.
We do this by allowing you to re-use the stream key several times on different livestreams.
This reduces the setup time and also removes possible errors in the configuration since once the configuration is completed it can be re-used.
#### What type to use ####
Best option is to always create a `STREAM`-type live source and benefit from 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`-type live source is a great idea to ensure that you get all analytics and can fully benefit from that even though the stream itself comes from a different provider.
- name: Live Overlay
description: |
Live Overlays are images displayed on top of a Livestream. You can have several Live Overlays active on the Livestream on the same time, but only one per template.
The `template_id` and the `livestream_id` creates a unique identifier a Live Overlay since you only can have one active Live Overlay per Template and Livestream.
Because of Template <-> Livestream relationship you don't need to store unique id:s for Overlays in you system, all you need to know is what template you're using.
***Notice*** that the overlay will only be displayed between the start and stop time of the Livestream.
If you are outside that window the overlay will not be displayed regardless of what value you set.
### Templates ###
Flowplayer provides a set of template that can be used by anyone broadcasting a livestream.
All templates have a set of replacement values that should be used to add your custom text to the overlay.
Below is a list of all existing templates and their replacement values:
| ID | Description | Replacement Values | Default X Position | Default Y Position | Default Opacity |
| ----- | -------- | ----------- | ----- | ----------- | ----------- |
| scoreboard | Our default scoreboard with black background and white text. Sample: ![alt text](data:image/png;base64,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) |
- ***HOME*** - The home team abbr.
- ***SCORE*** - The current score
- ***AWAY*** - The away team abbr.
| 5 | 5 | 100 |
A minimal sample request to use the `scoreboard` template on a Livestream, `{my-livestream-id}` using the API:
curl https://api.flowplayer.com/platform/v3/livestreams/{my-livestream-id}/overlays/scoreboard \
-H "x-flowplayer-api-key: {my-api-key}" \
-H "Content-Type: application/json" \
-X POST -d '{ "fields" : { "HOME" : "NYR", "SCORE" : "1-1", "AWAY" : "SJS" } }'
- name: Playlist
description: |
Playlists allow you to group videos into a list that plays in sequence in the player.
#### Selecting Playlist type ####
There are two types of playlists, `MANUAL` and `AUTOMATIC`, and which type to choose depends on how you want to manage your playlist.
`AUTOMATIC` playlists should be used if you want to filter its content through video metadata, e.g. tags or categories, and the sort order by popularity or publishing date.
If you instead want to control exactly which videos the playlist should contain and in what order they will be displayed, you can use the `MANUAL` type.
- name: Category
description: |
Categories can be used to categorize videos and livestreams within a workspace and are useful for creating automatic playlists and recommendations.
Categories are organized as a hierarchical tree structure. A video/livestream belongs to one single category.
- name: Video
description: |
With this API you can easily create, update, fetch, delete and list videos on a workspace or category. The API supports both remote and platform streamed videos.
#### Creating videos ####
To create a new video, an input file must be provided to the platform in some way. The `Create Video` API requires the source file to be downloadable by http(s) request. If you, need to upload the input file from a local computer we recommend to use the [Signed Url approach](https://flowplayer.com/developers/platform-api/signeduploadurl).
- name: Transcription
description: |
Automated transcription of the video input. Converts audio to text in minutes.
##### Note that transcription is only available to enterprise customers. #####
components:
schemas:
APIErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
property:
type: string
example: id
description: The field that did pass the validation
message:
type: string
example: id is required on this request
description: A message that tries to describe why the 'property' failed and what to change to pass the validation
message:
example: input validation failed
description: |
Message describing why the request failed
type: string
securitySchemes:
x-flowplayer-api-key:
type: apiKey
in: header
name: x-flowplayer-api-key
description: |
We currently support two types of API keys: User and Workspace keys. Both have advantages and limitations:
| API Key type | Description |
| ----- | ----------- |
| User | This key has the same access priviledges as the User it represents. It can, just as Users, have access to multiple Workspaces on an Organization |
| Workspace | This key only has access to the assets on the Workspace it belongs to. It can not access assets on other Workspaces |
You can find your Workspace API key and Site/Workspace id under [workspace/settings](https://app.flowplayer.com/workspace/settings).