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.
-
Basic Authentication:
User Name
andPassword
are required to be sent as part of every request to the Singular REST API. Basic Authentication is supported by all REST API commands. -
Access Token:
The authentication byAccess 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 Name
and
Password`, 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 usingAccess Control
in the App Toolbar of an app instance.
Authorization related error response¶
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¶
- Need help? Ask a question to the Singular Helpdesk.
- Found a bug? You can open ticket Submit a request.
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.