Spalk API Reference (1.3.0)

Welcome to the Spalk Developer API. This API allows you to connect the Spalk Virtual Commentary Studio to your existing live broadcast automation systems to seamlessly add remote commentary.

You can access the Spalk API via https://integration.spalk.tv/v1.

If you do not have a Spalk account, you can sign up for a trial account at https://app.spalk.tv/login. Once you have signed up, please email developer@spalk.tv to enable API access for your trial account. A trial provides access to full production functionality, aside from broadcasts being limited to 30 minutes in duration.

The Spalk API provides access to your live data. If you would like a sandbox account, please contact your Spalk representative for assistance.

We have decided to showcase the Spalk API with a Postman public workspace.

To get started, follow Access to the API to get API access and then fork our Postman collection:

If you have requests, feedback or questions, please request to join the Spalk Developer Community on Slack at https://spalk-tech.slack.com

The API is RESTful. All requests should be made over HTTPS, and accessed from https://integration.spalk.tv.

Requests

Most of the parameters and request data will be contained in the body of the HTTP request. The Spalk API accepts JSON in the HTTP request body. No other data format (e.g. XML) is supported.

Responses

The success or failure of an HTTP request is returned as a standard HTTP status code:

a 2xx code for success a 4xx or 5xx code for failure The response body will always be encoded in JSON format. No other data format (e.g. XML) is supported.

The Spalk API uses a cursor based model for paging of large result sets. Paging support is available for the following endpoints:

GET /events GET /inputs GET /teams GET /outputs All of these endpoints support an optional limit parameter. If this parameter is omitted, the default limit is 100. The maximum limit is 1000 for any single request.

Example

GET https://integration.spalk.tv/v1/events?Limit=2 HTTP/1.1
Host: integration.spalk.tv
- 200 Response

{
    "Meta": {
        "Next": "eyJsYXN0TW9kaWZpZWRUaW1lc3RhbXAiOjE1Njg2NzUzOTE3NTIsImNhbGxJZCI6ImE2YzVkMDgwLWQ0MWUtMTFlOS1hYzZiLWE5MTliMjAwYWFlNCIsIm9yZ2FuaXNhdGlvbklkIjoiOTQ4NzhhYzEtMDI3OS0xMWU5LWI0ZmEtNmJiYzgxMGEzZjJkIn0="
    },
    "Events": [ { ... }, { ... } ]
}

Endpoints that support paging return a Meta field in the response object, which includes a Next token to be used in subsequent requests.

Simply pass the next token in the query string of the next GET to retrieve the next page of results.

If there are no additional pages the next field will be empty.

Individual PUTS and POSTS are limited to 6MB total (JSON encoded) data size. If a given request contains more than 6MB of data we are unable to process that request.

In general for any date/time or timestamp types, this API will provide either of the following fields:

{fieldName}At: This is an RFC3339 formatted date/time. All date/times are UTC. Scheduled{fieldName}Date: This is an RFC3339 formatted date/time. All date/times are UTC.

Managing scheduled times for Spalk resources

The Spalk system will create, assign and destroy infrastructure based on the times associated with the resources you create. This section outlines the rules and best practises for managing times on your resources.

Creating resources

There is a small delay in provisioning infrastructure to resources. If you attempt to create resources for immediate use, the system may not be ready to accept streams and perform commentary for up to 5 minutes. We recommend scheduling resources at least 5 minutes in advance of attempting to use them.

Updating times

You may update scheduled times up to 5 minutes before they have elapsed. Once there is less than 5 minutes until the scheduled time elapses, the API will reject any updates to that time, and will carry out the associated resource actions (create/destroy) at the scheduled time.

There is one exception to this rule. You may update Event and Output ScheduledEndDates to end as soon as possible at any time. This is to allow you to free the input/output resources for reuse, and decrease your Spalk resource costs.

Due to the often unpredictable duration of live sports events, we recommend scheduling resource end times well in excess of expected end times, and updating the end time once you have confirmed the resources are no longer needed.

Spalk maintains infrastructure in a number of different AWS regions to enable you locate infrastructure geographically close to your customers and users.

Currently supported regions are:

• us-east-1: North Virginia (USA)
• eu-central-1: Frankfurt (Germany)
• eu-west-3: Paris (France)
• ap-southeast-1: Singapore
• sa-east-1: Sao Paulo (Brazil)

The Spalk API uses OAuth v2.0 client credentials flow to authenticate requests. You can manage your API access in the Spalk App at https://app.spalk.tv/organisation/developer

To authenticate with the Spalk API you need to follow these steps:

• 1. Create an API client and retrieve Organisation API Key
• 2. Generate an Access Token
• 3. Make Authenticated Requests

For more details on the OAuth 2.0 client credentials flow, see the overview at https://auth0.com/docs/flows/concepts/client-credentials

You must login as an Administrator to your account in the Spalk App at https://app.spalk.tv/login. Open the Organisation/Developer page.

You will find your Organisation API Key in the top right corner. If it is not present, create an API Client (see below) to generate an API Key for your organisation.

You must login as an Administrator to your account in the Spalk App at https://app.spalk.tv/login. Open the Organisation/Developer page, and add a new API client. This is a one time operation.

You require both an API client and Organisation API Key to make requests against the Spalk API.

Once the "API client" is created, you will be provided with the necessary details (OAuth 2.0 Client ID and OAuth 2.0 Client Secret) needed to create an access token.

Once you have created an "API client", the next step is to obtain a bearer token from the Spalk Auth Service at https://auth.spalk.tv/oauth/token. This step requires making an HTTP POST to the Authorization Service URL provided in the step above, with the request body containing an JSON encoded string with the following fields:

A javascript example of this is below:

const response = await fetch("https://auth.spalk.tv/oauth/token", {
  method: 'POST',
  body: JSON.stringify({
    client_id: "{CLIENT_ID_FROM_DEVELOPER_API}",
    client_secret: "{CLIENT_SECRET_FROM_DEVELOPER_API}",
    grant_type: "client_credentials"
  }),
  headers: { 'Content-Type': 'application/json' },
});

const { access_token } = response.json();

To make authenticated API requests, you must provide a valid bearer token in an HTTP Header:

Authorization: Bearer {access_token}

Once you have obtained an access token, you must provide this as a Bearer token for all subsequent API requests.

const response = await fetch("https://integration.spalk.tv/v1/events", {
  method: "get",
  headers: { Authorization: `Bearer ${access_token}`, 'X-API-Key': `${organisation_api_key}`, 'Content-Type': 'application/json' },
});

Access tokens expire after 3600 seconds (1 hour). It is up to the developer to implement appropriate refresh logic, by following the same token generation process above. Note that as flow is a client credentials flow, intended for machine to machine operations, we do not provide a token refresh endpoint. Instead, requesting a new access token using the same client_id/client_secret is sufficient.

• Add output.Label field to allow users to set free text labels shown on the Dashboard.

• Add GET /events/{eventId}/status to retrieve the current status of an event
• Add GET /teams/{teamId}/status to retrieve the current status of a commentary team
• Add GET /outputs/{outputId}/status to retrieve the current status of an output

• Add GET /commentators/favourites to quickly shortlist the users that have been marked as favourites for the organisation.

• Add route to link two events for redundancy

• Explicitly support latency parameters in SRT caller inputs
• Return SRT listener URLs in input.URL field that matches the Spalk Web UI and does not contain streamid parameter.
• Return SRT caller URLs to the input.Source and input.URL field in input responses.

• Support AWS MediaConnect Entitlement Input Type
• Support AWS MediaConnect Entitlement Output Protocol

• Published Spalk Event Scheduling API.

An event represents a live broadcast in the Spalk system. In order to use the Spalk system you must first schedule an event. Each event is provisioned individually, so there is a small startup time before the event goes live. We recommend scheduling your events at least 5 minutes before you are ready to send the live feed.

Events have some restrictions on modifications once they have been created:

• You cannot update the input type of an event once it has been created.
• You cannot update the scheduled start time within 5 minutes of the previously scheduled start time.
• You cannot update the scheduled end time within 5 minutes of the previously scheduled end time.
• You cannot delete an event less than 5 minutes before the scheduled start time.

If your application needs to make any of these modifications, simply end and/or delete that event and create a new one that matches your needs.

For more information see Managing scheduled times for Spalk resources.

For information on supported input protocols see Inputs.

An input represents an entrypoint that is used to send media to the Spalk system. This media will typically be a clean broadcast with no commentary. These routes are provided to enable the use of persistent endpoints that remain static and can be reused between live events.

If you do not need inputs to persist between events, single-use endpoints can be created by including an Input with a Type and Region in the Inputs field of the POST request body in the /events endpoint.

Currently supported input protocols include:

• AWS MediaConnect Entitlement
• RTMP (Push)
• SRT (Caller mode)

In order to use AWS MediaConnect as input to your Spalk event, you must entitle our AWS account with ID 496668274218 to access to the stream. Instructions on how to grant an entitlement can be found here. Step 13 shows where to find the entitlement ARN, provided to Spalk in the Input.Source field.

A team is a set of users who commentate an event together on the same audio track. When they log in, they are able to see and hear each other, all of their audio is mixed into the same audio track on output. The team can be made up of audible members (commentators) and non-audible members (producers) who help facilitate the broadcast. If a user needs to speak to their team without being heard on the broadcast, they can do so using 'Talkback mode'.

Note: Teams do not persist between events, so a new team must be created for each new event where users commentate together.

There is currently a limit of 5 concurrent users in the commentary studio for a single team.

A commentator is a user that can be assigned to a commentary team.

An output represents a destination downstream of Spalk that will receive the mixed stream containing the commentary from the selected commentary teams.

Outputs can be created, modified or deleted at any point up until they are live. Once they are live, only the scheduled end date may be modified.

For more information see Managing scheduled times for Spalk resources.

The tracks present in the output are subject to a few rules.

• By default, all tracks in the input will be passed through to the output. As of a result of this, creating an output with no tracks specified will simply result in an output that passes all the input tracks through without manipulation. An important note about these tracks is that they will not be present in any of the responses from these endpoints.
• The input tracks can be explicitly excluded from the output using the ExcludeTrack property. Tracks generated by Spalk must be included in the Tracks property to be present in the output.
• There is a limit of one Team track per output of any type.
• SRT and AWS MediaConnect outputs may include any mix and number of output tracks.
• RTMP outputs are limited by the FLV container format, which requires there is no more than one video and one audio track. Any tracks included a RTMP output will override the relevant audio or video track from the input.

The following table describes the supported combination of track selectors.