Welcome to the Cluvio public API!

The Cluvio public API can be used to programmatically view and manage your organization's Cluvio account from your own backend application. By using the Cluvio API, you can integrate the functionality of Cluvio into your organization's software stack to further automate your Cluvio-driven business analystics.

Security

The Cluvio public API is an HTTP API with Transport Layer Security. Individual requests are authenticated via API keys, which are described in more detail below.

JSON

All data transmitted in requests and responses on the Cluvio API is encoded in JSON. The request and response bodies of most create-read-update operations furthermore adhere to the structure defined by JSON:API. Whether a request or response body uses a JSON:API or regular JSON structure is identified in this documentation in the request body schema and response schema definitions of each API operation, respectively. The MIME type application/json identifies plain JSON and application/vnd.api+json identifies JSON according to JSON:API. These MIME types are transmitted in the Accept and Content-Type HTTP headers.

⚠ Any JSON attributes in API responses which are not documented must not be relied upon. Such attributes are not part of the public API and may disappear or be renamed without notice.

Clients

At this time, there are no programming-language-specific clients provided by Cluvio for the Cluvio API. It is easy to get started with the Cluvio API from any programming language by using your preferred HTTP client library. For ad hoc experimentation, command-line tools like curl can be used.

The Cluvio API uses two types of servers, API Servers and Data Servers.

The Cluvio servers are available in both of Cluvio's deployment locations, namely the US and the EU. When using the Cluvio API it is important to use the Cluvio servers corresponding to your Cluvio account location. You can see your Cluvio account location in the organization's admin settings.

Most Cluvio API operations are provided by the API servers and thus grouped as API Server Operations on the left-hand side navigation. API server operations require an API key for request authorization that has the permissions required for the operation. Each operation lists the required API key permissions.

In contrast, operations that fetch schema data or query result data must be performed on Cluvio data servers. These are grouped as Data Server Operations on the left-hand side navigation and require a short-lived data access token for request authorization. Data access tokens are obtained from certain API server operations.

EU Servers

• API server: https://api.eu.cluvio.com/
• Data server: https://data.eu.cluvio.com/

US Servers

• API server: https://api.us.cluvio.com/
• Data server: https://data.us.cluvio.com/

An API key grants access to the API server operations. API keys can be created, updated and deleted by any admin in your organization. See API Keys in the Cluvio admin settings for details on managing API keys.

Usage

Each API key has a secret token, sometimes just referred to as the API key's secret. This secret is used to authenticate requests on the Cluvio API by including it in the request's Authorization header as follows:

Authorization: Api <secret>

The custom authentication scheme Api identifies the following secret to be an API key secret. The placeholder <secret> is to be replaced with your API key secret.

API key secrets do not expire and are valid for use on the Cluvio API for as long as the API key exists and is enabled.

Permissions

An API key has a set of permissions and some permissions may be restricted to specific resources, like datasources. In the documentation of an API operation, the AUTHORIZATIONS section lists the permissions required for the operation. For example,

AUTHORIZATIONS:
  ApiKey (Manage Datasources)

indicates that the API key must have the Manage Datasources permission to perform the operation.

A data access token is a short-lived token that grants access to a data server operation. It may be obtained in the response of an API server operation and is always provided together with a data key. The data key together with the data access token uniquely identify the data to fetch from a Cluvio data server.

Usage

To use a data access token, include it in the request's Authorization header as follows:

Authorization: Data <token>

The custom authentication scheme Data identifies the following text to be a data access token. The placeholder <token> is to be replaced with the token obtained from the Cluvio API server.

Note: It is important to issue the data server request against the same Cluvio server location as the API server request that was used to obtain the data access token. For example, if you issued an API request to api.eu.cluvio.com and received a data key and data access token, the request to fetch the data must be sent to data.eu.cluvio.com.

Data access tokens expire within minutes. When received in a response from a Cluvio API server, they must be used immediately on a Cluvio data server, if the client wants to fetch the associated data.

The following is a list of changes made to this API version since the initial release, in chronological order.

July 31st 2024

The values and value_names attributes are now available in the Create Filter and Update Filter operations to create and update drop-down filters with manual / static options. Use the Get Drop-Down Filter Options operation to fetch the options for an existing drop-down filter.

July 18th 2024

The include query parameter is now available on the Get User Group operation and can be used to include related users and dashboards in the response.

July 3rd 2024

A new operation Create Dashboard Backup is now available. This operation returns a JSON backup for a Cluvio dashboard that can later be used to create a new dashboard from a backup in the Cluvio App UI. See also Backup Dashboard in the Cluvio User Documentation.

Note: The backup JSON format is an internal format whose structure is not publicly documented and subject to change. Backup JSON files can only be used with the Cluvio App UI.

June 26th 2024

The all_time aggregation option is now available and can be used as an input value for a custom aggregation filter. Note that the filter must be explicitly configured to allow "All Time" aggregation in order for the input value to be accepted.

June 4th 2024

The sql_snippet relationship has been added to SqlSnippet response objects, for example in the response of the Get SQL Snippet operation.