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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) | | 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).