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:

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).