Skip to content

Singular REST API v1.0

This document describes the REST API and resources provided by Singular.live. The REST APIs are for developers who want to integrate the Singular.live platform into their application.

Singular's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The response format is JSON. Your methods will be the standard HTTP methods like GET, PUT, POST and DELETE.

You need valid User Credentials or an Access Token to send requests to the API endpoints. You can use your User Name and Password from your Singular Account or create a specific user to for API Access in the User Administration of your Singular Account.

Because the REST API is based on open standards, you can use any web development language to access the API.

Authentication

The Singular REST API supports two methods for authentication.

  1. Basic Authentication:
    User Name and Password are required to be sent as part of every request to the Singular REST API. Basic Authentication is supported by all REST API commands.

  2. Access Token:
    The authentication by Access Token is supported by REST API commands controlling Singular App Instances only. This may look limiting but gives full access to update data and control Singular compositions during playout and live productions.

If you do not have a ´User NameandPassword`, you can ask you Singular Account Administrator to create one for you. Please refer to the Singular Knowledge Base for managing users and permissions.

If you do not have an Access Token, you can generate one using Access Control in the App Toolbar of an app instance.

If the User Name and Password are missing, malformed, or invalid, you will receive a 401 Unauthorised response code and the following JSON response:

{
    "error": {
        "message": "Unauthorized – Authentication credentials were missing or invalid",
        "type": "Bad Request",
        "code": 401
    }
}

Structure of the REST URLs

URLs for the Singular REST API resouce hve following structure:

Structure:

  • Generic Endpoint:
https://app.singular.live/apiv1/{resource-name}

Examples:

  • App Instances Endpoint:
https://app.singular.live/apiv1/appinstances
  • Global Data Endpoint:
https://app.singular.live/apiv1/datanodes
  • Compositions Endpoint:
https://app.singular.live/apiv1/compositions

Error Codes

Singular.Live API uses the following error codes:

Error Codes

Error Code Meaning
400 Bad Request – The request was invalid. An accompanying error message will explain why.
401 Unauthorized – Authentication credentials were missing or invalid
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
500 Internal Server Error – We had a problem with our server. Please try again later.
502 Bad Gateway – Singular.Live is down or being upgraded.
503 Service Unavailable – Singular.Live is up, but overloaded with requests. Please try again later.

Find more documentation

  • Singular REST API Reference: here...
  • Singular REST API Developer Guide: here...
  • Singular REST API Demos and Code Examples: here...

Getting Help

Terms of Use

For information on API terms of use and privacy, refer to our policy document at http://www.singular.live/terms-of-service and http://www.singular.live/privacy-policy.