Twinkly Runtime API Reference

Owned by Sirio (Unlicensed)
Last updated: Feb 26, 2024 by Matteo Magrin
18 min read

A Twinkly device (both Retail & PRO) can be remotely controlled through a very simple and powerful API interface. The device(s) to be controlled needs to be on a network with port 8883 (the standard MQTT/TLS port) open for internet access (outbound to mqtt.twinkly.com and mqtt-pro.twinkly.com).

In the same way we can control a single device we can also control a group of devices; for this reason we introduced the concept of “object”.
A Twinkly object is a “virtual device” composed by 1 or more physical devices. A Twinkly object let you control simultaneously from 1 to a virtually infinite number of Twinkly devices grouped together.

To remotely control a Twinkly object you need to have an active Twinkly Account.

Moreover, it is also possible to group a set of objects inside an installation, and control the installation through Runtime API.

The endpoints used to handle a Twinkly objects are different for production and staging environments:

PRODUCTION: https://api.twinkly.com
STAGING: https://api-staging.twinkly.com

Authentication

All the API required an authentication through a bearer token, that could be obtained with a call to the authentication endpoint or using an OAuth2 authentication flow.

Authentication Endpoint

POST /v2/auth
Body
{ "username": "<TWINKLY_ACCOUNT_EMAIL>", "password": "<TWINKLY_ACCOUNT_PASSWORD>" }
CURL example
curl -X "POST" "https://api.twinkly.com/v2/auth" \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{ "username": "marsellus.wallace@pf.com", "password": "M14W4ll4c3" }'
Response (example)

The token obtained has a validity of 1 day: after this time, it will expire and needs to be refreshed using the refresh token endpoint, and the refresh token obtained with the token.

OAuth2 Authentication Flow

As per OAuth2 specification, Twinkly APIs provide the following endpoints:

  • Authorization endpoint: https://api.twinkly.com/v2/auth/login

  • Token endpoint: https://api.twinkly.com/v2/auth/token

The use of this authentication flow require a pre-configured clientId and clientSecret to be used in the call

Authorization endpoint

This GET endpoint will show a webview where the user can enter his/her authentication credentials (or logging in using its Apple or Facebook account). The accepted parameters (as query parameters) are:

  • client_id: the client ID requesting the authorization

  • redirect_uri: the redirect URI the browser will redirect to upon successful validation of credentials

  • response_type: the type of redirect

  • scope: the optional scope of the request

  • state: a value passed by the third part service, that is completely opaque for Twinkly backend and that will be sent back to the redirect url

Token endpoint

This POST endpoint is used to obtain the actual token (or refresh an existing one obtained through OAuth2) to be used in the subsequent calls to Twinkly APIs.

The accepted parameters (as JSON body) are:

  • code: the authentication code obtained from a call to authorization endpoints

  • client_id: the ID of client requesting the token

  • client_secret: the secret of client requesting the token

  • grant_type: type of grant requested: could be one of "authentication_code" or "refresh_token"

  • refresh_token: the refresh token, if the grant type is set to "refresh_token"

  • redirect_uri: the redirect URI the browser will redirect to

Token Refresh

To refresh an expired token:

Body
CURL example
Response (example)

Retrieve user objects

Get all objects that a user owns. Each object is the “static” descriptor of the object, that is its name, unique identifier, owner, led count, etc.

Optional query parameters
Headers
CURL example
Response (example)

Retrieve device configuration

Get the (optional) objects and installations that a device belongs to.

Headers
CURL example
Response (example)

Retrieve the runtime status of an object

The runtime status is the “live” status of an object currently connected to the internet. It will report the connection status to the internet (online/offline), the current operation mode, the list of movies available (for objects that support them), etc.

Headers
CURL example
Response (example)

Retrieve the runtime status of a group of objects

It is possible to retrieve the runtime status of a group of objects with a single call, instead of calling the single get runtime for every object.

Headers
Query parameters

The available query parameters are:

  • objectIds: a comma-separated list of object IDs to be returned in the response; this field is mandatory

  • config: a boolean flag that indicates to return also che configuration part of the runtime object. It is an optional parameter, and could be 0 or 1; if not specified defaults to 1 (configuration returned)

CURL example
Response example

The response will have the following possible return codes:

  • 200, if everything is fine

  • 401, if the authorization failed

  • 500, if some internal error happens

The body is a dictionary, where the key is the object ID and the value is the following object:

The API will always return the complete list of objects, also for objects that I don’t have the permission to see or not existent: in this case, the runtime field of the descriptor will not be present, and instead an error key will contain the error string

Send runtime command to an object

Send a command to an object. The specific command to send is specified by the payload.

Headers
Body

The body of specific commands are described in the following paragraphs. Apart from command and params, here are listed the common parameters, which it is possible to send with each command, and which modify in some way the command execution.

The parameters are as follow:

  • async: boolean flag that set the execution mode for the command; default to false, except for installEffect command. If set to true, the response will contain the command identifier to be used when polling for command execution status

  • timeout: integer that set the number of seconds to wait for a synchronous command to finish; default to 10 seconds

  • unreliable: boolean flag that, if true, will send the command without waiting for response from devices: this means that, apart from internal system errors, the api call will always return 200, but it is not guaranteed that the command has had the effect expected; default to false

  • forceOffline: boolean flag that instruct the backend to send the command to devices, even if the runtime status report the online property as false; default to true

The allowed commands are described below.

Turn ON an object

Body
CURL example

Turn OFF an object

Body
CURL example

Set a specific mode

Body
CURL examples

Plays the current effect (configured by the internal state of device):

Play a specific effect:

Play the current configured color:

Play a pre-installed effect

Body
CURL example

Set Brightness on an object

Body
CURL example

Set a Color on an object

Set a color on all leds of an object.

Body

It is also possible specify a color using RGB coordinates (only if object devices support RGB color coordinates*):

CURL example

Play a pre-installed playlist

Body
CURL example

Get runtime command execution status for an object

If a command is sent in asyncronous mode, the send command API will return a command identifier, that will allow the client to query about the command execution.

The commandId path parameter is the ID returned by the API that send the asynchronous command execution request.

Headers
CURL example
Response example

The response will have the following possible return codes:

  • 200, if everything is fine

  • 401, if the authorization failed

  • 404, if the command ID is not found

  • 500, if some internal error happens

The fields in the response are as following:

  • objectId: the ID of the object where the command has been executed

  • commandId: the ID of the command that we are asking the status of

  • status: the status of the command execution; could be one of success, failed or running

  • progress: show the overall progress of the command execution, based on the execution status of the command in every devices of the object

Retrieve the runtime status of an installation

The runtime status is the “live” status of an installation, that is a group of objects, currently connected to the internet. It will report the connection status to the internet (online/offline), the current operation mode, the list of movies available (for objects that support them), etc.

Installation as a group of objects [LEGACY]

The parameters are as follow:

  • objectIds: a comma-separated list of object identifiers

Headers
CURL example

Installation as an entity

The parameters are as follow:

  • installationId: the unique identifier of the installation

  • config: optional boolean parameter (could be 1 or 0, defaults to 1 if not present), to allow configuration descriptor to be present in the returned response

Headers
CURL example
Response (example)

Retrieve the runtime status of a group of installations

It is possible to retrieve the runtime status of a group of installations with a single call, instead of calling the single get runtime for every installation.

Headers
Query parameters

The available query parameters are:

  • installationIds: a comma-separated list of installation IDs to be returned in the response; this field is mandatory

  • config: optional boolean parameter (could be 1 or 0, defaults to 1 if not present), to allow configuration descriptor to be present in the returned descriptors of the installations

CURL example
Response example

The response will have the following possible return codes:

  • 200, if everything is fine

  • 401, if the authorization failed

  • 500, if some internal error happens

The body is a dictionary, where the key is the installation ID and the value is the following object:

Send runtime command to an installation

Send a command to an installation. The specific command to send is specified by the payload.

Headers
Body

The body of specific commands are described in the paragraphs of the objects command. Apart from command and params, here are listed the common parameters, which it is possible to send with each command, and which modify in some way the command execution.

The parameters are as follow:

  • async: boolean flag that set the execution mode for the command; default to false, except for installEffect command. If set to true, the response will contain the command identifier to be used when polling for command execution status

  • timeout: integer that set the number of seconds to wait for a synchronous command to finish; default to 10 seconds

  • unreliable: boolean flag that, if true, will send the command without waiting for response from devices: this means that, apart from internal system errors, the api call will always return 200, but it is not guaranteed that the command has had the effect expected; default to false

  • forceOffline: boolean flag that instruct the backend to send the command to devices, even if the runtime status report the online property as false; default to true

The allowed commands are described in the section of the runtime object commands, because the commands sent to an installation will be sent to the objects part of the installation.

Get runtime command execution status for an installation

If a command is sent in asynchronous mode, the send command API will return a command identifier, that will allow the client to query about the command execution.

The commandId path parameter is the ID returned by the API that send the asynchronous command execution request.

Headers
CURL example
Response example