API

CloudTables provides a REST API that can be used to embed data sets into a HTML page and retrieve data from CloudTables.

The documentation below details the REST URLs, options and returned data - this is the raw implementation which can be used with any server-side environment that can make HTTP requests. We also provide API tool kits for a number of server-side environments that wrap this API into an easy to use package using paradigms suitable for that environment. For full details, please refer to the documentation for each library:

• cURL
• Java
• .NET
• NodeJS
• PHP

Rate limits

Please note that we apply a rate limiter to our API. This is currently 500 requests over a a 15 minute period. If you require more than this, please get in touch.

Access token

POST https://sub-domain.cloudtables.io/api/1/access

Get an access token that can be used to securely embed a CloudTable into an HTML page.

Body parameters:

Name	Required	Type	Description
key	Required	String	The API key which will allow access (and thus assign the roles that can be used for access).
clientId	Optional	Any	A unique id for the client accessing the table on your system. While this is optional it is a recommended parameter as it is useful for tracking requests in CloudTables' analytics.
clientName	Optional	String	A label that can help identify a user - e.g. a name or e-mail address. Typically the clientId will be an integer or UUID which mean you'd need to look up the user to understand who made what changes. Note that while the clientId should be unique per client and not change - the clientName can change and will be updated to reflect the latest value given (e.g. if a user modifies their name in your own system).
conditions	Optional	Array or Object	Conditions to apply to the accessed data. Only data meeting the requirements will be returned. Please see the conditional data access documentation for full details.
duration	Optional	Integer	Access token's time to first use, or idle time out in seconds. If there are no actions after the given period of time the access rights of the token will be revoked and a new token would be required to carry on. Note that a web-page using a token will retain the access granted to it while the page is open. Defaults to 20 minutes.
role	Optional	String	The name of the role that should be used for the generated access token (if assigned to the API key - if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used.
roles	Optional	String[]	Similar to role but allows multiple roles to be specified.

Response:

JSON object with the following parameters:

Name	Type	Description
token	String	The access token that can be used in the embed <script> request. See the embed documentation.

Datasets summary

GET https://sub-domain.cloudtables.io/api/1/datasets

Get a list of all data sets which can be accessed by the role(s) available to this API key and summary information about each data set.

Query parameters:

Name	Required	Type	Description
key	Required	String	The API key which will allow access (and thus assign the roles that can be used for access).
role	Optional	String	The name of the role that should be used (if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used.
roles	Optional	String[]	Similar to role but allows multiple roles to be specified.

Response:

JSON object with the following parameters:

Name	Type	Description
datasets	Array	Information about the accessible data sets.
datasets[].deleteCount	Integer	Number of rows deleted from the data set.
datasets[].id	String	ID of the data set.
datasets[].insertCount	Integer	Number of rows that have been inserted into the data set.
datasets[].lastData	ISO8601	Date / time of the last create, update or delete on the data set.
datasets[].name	String	Name of the data set
datasets[].readCount	Integer	Number of times the data set has been read.
datasets[].rowCount	Integer	Number of rows that are currently in the data set.
datasets[].updateCount	Integer	Number of update operations on the data set.

Dataset data

GET https://sub-domain.cloudtables.io/api/1/dataset/{id}/data

Get the data for a specified data set, where {id} in the URL is the data set id, per the /datasets API. The data set ID can also be found in the Data set inspector of the Data tab for the data set.

Query parameters:

Name	Required	Type	Description
key	Required	String	The API key which will allow access (and thus assign the roles that can be used for access).
role	Optional	String	The name of the role that should be used (if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used.
roles	Optional	String[]	Similar to role but allows multiple roles to be specified.

Response:

JSON object with the following parameters:

Name	Type	Description
columns	Array	Information about the columns of data.
columns[].id	String	Column ID. This will have the prefix c- for computed values and dp- for data points, each followed by a unique number.
columns[].link	String	If the data point is from a linked data set, this is ID for the link (it will have the prefix l-). Otherwise, it will be null if not from a linked data set.
columns[].name	String	Defined name for the column.
data	Array	The data for the data set.
data[].id	Integer	ID of the row.
data[].dv	Integer	Data version of the row.
data[].*	See below	Data for the row where * is the id of the matching column. If representing a linked column the value will be an array of objects for the link data points and calculated value, while the name will match the link id.

Please note that at this time the following formatting is used for the various data types:

• date - ISO 8601 (date only)
• datetime - ISO 8601
• number - Unformatted number
• text - Plain text
• time - ISO 8601 (time only).