Introduction

Welcome to the Cumul.io API! You can use our API to integrate dashboards within your own applications, create or update datasets, open up new data sources or automate just about anything about your Cumul.io experience.

We offer 3 main APIs that are documented in detail:

• Core API: build datasets & dashboards, manage users & groups, send event data to Cumul.io
• Integration API: bindings to seamlessly integrate dashboards within your own applications
• Plugin API: connect your own data stores or APIs with a flexible data adapter

You can start reading our guides that cover common use cases or dive right into the API specifications for further detail.

All APIs use REST with default HTTP verbs. Content is sent as JSON.

In case of questions, you can reach our team at api@cumul.io -- or via the in-platform chat.

Good luck, and have fun!

Guides

Dashboard Integration

Quickstart

Integrating a dashboard in your own application/platform is a simple two-step process, with a server-side and a client-side action.

1. Generate an authorization token (server-side)

2. Embed the dashboard in your own application/platform (client-side)

Step 1. Generate an authorization token

Replace with your API key & token, an expiry moment of choice, the id of the dashboard & the id's of the datasets used in the dashboard

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z"
  }
}
EOF

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ],
  expiry: new Date(new Date().getTime() + 300 * 1000)
});

promise.then(function(result){
  // return the result to the client
})

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  )
));
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
    .put("securables", ImmutableList.of(
        "< dashboard id >", 
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .build()
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

This returns a JSON object with an id/token combination that we will use to integrate:

{ 
  "type": "temporary",
  "id": "< the authorization key >",
  "token": "< the authorization token >"
  // ...
}

In this step, your server-side code makes an API request to retrieve an authorization token. The result of this request is a key/token combination that will be used to in step 2 to securely embed the dashboard in your application/platform.

The API request, is a 'create' request for an authorization. In this example we set an expiry date and define the securables (the dashboard and the datasets used in the dashboard) that we grant access to.

Property	Description
type string	temporary Use the value 'temporary' for integrating a dashboard.
securables array	List of id's of securables to which you want to grant access to. It is advised to add this to your request and to limit it to the id of the dashboard you want to integrate and the id's of the dataset(s) used in the dashboard.
expiry date (ISO 8601)	Date/time when this authorization will cease working. Defaults to no expiry. It is advised to only use short-living tokens (max. 24 hours) for maximum security.

You can also add Filters that you want to apply and/or add viewer metadata information. For a list of all properties that you can use in the request, check Authorization in the Core API.

The request returns a JSON object that contains an authorization id & token. This is the key/token combination that will be used in our next step (client-side) to integrate the dashboard in a secure way.

Step 2. Embed the dashboard in your application/platform

Add a container element to your page with DOM ID of my-dashboard.

<div id="my-dashboard"></div>

Add a script to your page to load the dashboard in that container, use the key & token from the previous step.

<script type="text/javascript">
  (function(d, a, s, h, b, oa, rd) {
    if (!d[b]) {oa = a.createElement(s), oa.async = 1;
    oa.src = h; rd = a.getElementsByTagName(s)[0];
    rd.parentNode.insertBefore(oa, rd);} d[b]=d[b]||{};
    d[b].addDashboard=d[b].addDashboard||function(v) {
    (d[b].list = d[b].list || []).push(v) };
  })(window, document, 'script',
    'https://cdn-a.cumul.io/js/cumulio.min.js', 'Cumulio');

  Cumulio.addDashboard({
    dashboardId: '< Dashboard id you want to embed >',
    container: '#my-dashboard',
    key: '< authorization key from step 1 >',
    token: '< authorization token from step 1 >'
  });
</script>

To integrate a dashboard in your webpage, we use the Integration API.

First, add a DOM element to your body that will act as the dashboard container. Give it an id or a class name so that you will be able to reference it later on.

Once you have the container element in your page, load the dashboard in that container using the javascript snippet. The script will check whether the Integration API is loaded in your webpage. If not, it will be retrieved from our servers.

To add a dashboard to the container in your page the addDashboard function is used. This function uses the generated key/token combination from step 1, together with the id of the dashboard and the selector for the dashboard container to load the dashboard.

Parameter	Description
dashboardId uuid	This is the id of the dashboard that you want to embed.
container string	The DOM selector for identifying the container in which the dashboard will be embedded.
key uuid	The authorization id from step 1.
token string	The authorization token from step 1.

You can (optionally) add extra parameters to choose which screenmode or language will be loaded and/or to style the container when loading the dashboard. This to ensure a perfect fit with the style of your page. For all parameters check the addDashboard function in the Integration API.

That's it! With these steps, you securely integrate a dashboard in your application/platform!

Next steps

• Add Parameters
• Add account_overrides
• Add viewer metadata
• Set an initialization filter
• Set language
• Set screenmode
• Chart integration

Related topics to integration

• Retrieving a dashboard id
• Retrieving a dataset id
• Retrieving a column id
• Retrieving a chart id
• Retrieving an account id
• Remove/replace a dashboard
• Invalidating tokens

Add Parameters

You can add Parameters to your authorization requests to filter the data in your embedded dashboards.

First you need to create and define the Parameter, after which you can set the Parameter to a value of your choice when creating the authorization request.

Create and define the Parameter

First create the Parameter via the Parameter overview. Input the name, data type and default value for the Parameter.

Once you created the Parameter, use it as a global or chart filter. A global filter is a filter that has effect on every chart in the dashboard, a chart filter is a filter that has effect on only one chart in the dashboard.

Set the Parameter

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    metadata: { 
      "< Parameter name > " : "< value to be applied >"
      }
  }
}
EOF

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
});

client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  username: '< end-user username >',
  name: '< end-user name >',
  email: '< end-user email >',
  metadata: { 
    Parameter_name: '< value to be applied >'
   }
});

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'username' => '< end-user username >',
  'name' => '< end-user name >',
  'email' => '< end-user email >',
  'metadata' => array( 
    '< Parameter name >' => '< value to be applied >'
   )
));
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >",
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("username", "< end-user username >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("metadata", ImmutableMap.builder()
    .put("< Parameter name >", "< value to be applied >")
    .build()
  )
  .build()
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.username = "< end-user username >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.metadata = new {
  parameter_name = "< value to be applied >"
}

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

Set the Parameter to the desired value when creating the authorization. To do this, extend the code snippet used in step 1 by adding a metadata parameter to the request in which you specify the Parameter and set its value.

Property	Description
type string	temporary Use the value 'temporary' for integrating a dashboard.
securables array[uuid]	List of id's of securables to which you want to grant access to. It is advised to add this to your request and to limit it to the id of the dashboard you want to integrate and the id's of the dataset(s) used in the dashboard.
expiry date (ISO 8601)	Date/time when this authorization will cease working. Defaults to no expiry. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
metadata object	Parameter name and value. The value should be a number, string, boolean or array depending on the parameter type set when creating the parameter.

Add Account overrides

Override the host property of your standard connector (database) account

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    "account_overrides": { 
      "< Your account_id >" : {
        "host": "< The new database host to connect to. >"
      }
    }
  }
}
EOF

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
});

client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  username: '< end-user username >',
  name: '< end-user name >',
  email: '< end-user email >',
  account_overrides: { 
    '< your account_id >': {
      host: '< The new database host to connect to. >'
    }
   }
});

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'username' => '< end-user username >',
  'name' => '< end-user name >',
  'email' => '< end-user email >',
  'account_overrides' => array( 
    '< your account_id >' => array(
      'host' => '< The new database host to connect to. >'
    )
   )
));
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >",
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("username", "< end-user username >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("account_overrides", ImmutableMap.builder()
    .put("< your account_id >", ImmutableMap.builder(
      .put("host", "< The new database host to connect to. >")
      .build()
    ))
    .build()
  )
  .build()
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.username = "< end-user username >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.account_overrides = new Dictionary<string, object> {
  "<your account_id>", 
  new {
    "host" = "< The new database host to connect to. >"
  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

Your data may be split over databases per client. In such case, you can create multitenant dashboard in Cumul.io using the account_overrides functionality. An account in Cumul.io contains the information that is necessary to access a certain plugin or database. The account_overrides functionality allows you to dynamically override one or multiple of these properties.

You can override the account properties when creating your authorization requests to switch between databases. You could also use this approach to change the user/password in a single database in case your database provides row-level security. Row-level security in this context means that the database can automatically filter out rows based on the credentials.

You can use the account_overrides if you are using one of the standard Cumul.io connectors (MySQL, PostgreSQL, ...) as well as if you are using a Plugin to connect your data.

You can find your account_id by going to Profile > Connected Accounts and looking for your account. Alternatively you can perform an API call to get your account_ids.

Property	Description
type string	temporary Use the value 'temporary' for integrating a dashboard.
securables array[uuid]	List of id's of securables to which you want to grant access to. It is advised to add this to your request and to limit it to the id of the dashboard you want to integrate and the id's of the dataset(s) used in the dashboard.
expiry date (ISO 8601)	Date/time when this authorization will cease working. Defaults to no expiry. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
account_overrides object	Let this token override the connection to one or more data connections (to a Plugin or database). You can use this to dynamically route requests to different endpoints (eg. the correct endpoint per client in a single-tenant setup). All overrides are optional -- if not specified, the value as configured on the original Account will be used instead.
account_id object	The database account id for which you want to override properties as property name.
host string	The new database host to connect to. The database must be of the same type as the originally configured database.
port string	The new port to connect to.
user string	The new user to use when connecting.
password string	The new password to use when connecting.
schema string	The new schema to retrieve data from.
table string	The new table to retrieve data from.
account_id object	The Plugin account id for which you want to override properties as property name.
base_url string	The new base URL that will be called.
host string	The new host value that will be sent as X-Host header to the Plugin.
key string	The new key value that will be sent as X-Key header to the Plugin.
token string	The new token value that will be sent as X-Token header to the Plugin.
table string	The new canonical dataset identifier defined in the Plugin to retrieve data from.

Viewer metadata

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    // Optional 'user context'
    username: "< end-user username >",
    name: "< end-user name >",
    email: "< end-user email >",
    metadata: { ... optional end-user metadata }
  }
}
EOF

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
});

client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  // Optional 'user context'
  username: '< end-user username >',
  name: '< end-user name >',
  email: '< end-user email >',
  metadata: { ... optional end-user metadata }
});

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'username' => '< end-user username >',
  'name' => '< end-user name >',
  'email' => '< end-user email >',
  'metadata' => array( ... optional end-user metadata )
));
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >",
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("username", "< end-user username >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("metadata", ImmutableMap.of(" ... optional end-user metadata "))
  .build()
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.username = "< end-user username >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.metadata = new {
  metadataLine1 = "< ... optional end-user metadata >"
  // ...
}

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

When creating authorization tokens, it is possible to include viewer metadata in the request.

This allows you, for example, to audit who viewed which dashboards.

To do this, extend the code snippet used in step 1 by adding optional parameters username, name, email and metadata to the request.

Property	Description
type string	temporary Use the value 'temporary' for integrating a dashboard.
securables array[uuid]	List of id's of securables to which you want to grant access to. It is advised to add this to your request and to limit it to the id of the dashboard you want to integrate and the id's of the dataset(s) used in the dashboard.
expiry date (ISO 8601)	Date/time when this authorization will cease working. Defaults to no expiry. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
username string	(optional) The username of the end-user.
name string	(optional) The name of the end-user.
email string	(optional) The email address of the end-user.
metadata array	(optional) Additional metadata can be added in this parameter.

Set an initialization filter

Replace with your API key & token, an expiry moment of choice, the id of the dashboard & the id's of the datasets used in the dashboard, the chart id, the expression to be used and the filter value of your choice.

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    "filters": [
      {
        clause: "where",
        origin: "initialization",
        chart_id: "< chart id of a chart contained in the dashboard >",
        expression: "? = ?",
        value: "< value to be applied to the expression >"
      }
    ]
  }
}
EOF

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  filters: [
    {
      clause: 'where',
      origin: 'initialization',
      chart_id: '< chart id of a chart contained in the dashboard >',
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }
  ]
});

promise.then(function(result){
  // return the result to the client
})

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'filters' => array(
    array(
      'clause'     => 'where',
      'origin'     => 'initialization',
      'chart_id'   => '< chart id of a chart contained in the dashboard >',
      'expression' => '? = ?',
      'value'      => '< value to be applied to the expression >'
    )
  ),                      
));
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >", 
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "initialization")
    .put("chart_id",     "< chart id of a chart contained in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "chart",
    chart_id = "< chart id of a chart contained in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

To do this, extend the code snippet used in step 1 by adding a filters parameter to the request.

For an initialization filter, it is not needed to specify the securable_id or column_id in the filters parameter. This is because a filter object can have multiple columns, coming from different datasets.

Property	Description
type string	temporary Use the value 'temporary' for integrating a dashboard.
securables array[uuid]	List of id's of securables to which you want to grant access to. It is advised to add this to your request and to limit it to the id of the dashboard you want to integrate and the id's of the dataset(s) used in the dashboard.
expiry date (ISO 8601)	Date/time when this authorization will cease working. Defaults to no expiry. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
filters array[object]
clause string	Timing of application of the filter. Possible values: where (applied before aggregation/grouping, for example, only select rows with a specific price), having (applied after aggregation/grouping, for example, to select only groups in which the total price exceeds a specific value)
origin string	This parameter specifies the level to apply the filter. For an initialization filter, this parameter should be set to initialization.
chart_id uuid	The id of the chart you want to apply the filter to. This chart needs to be contained in the dashboard you specified in the securables parameter.
expression string	The expression to be used in your filter formula. The possible filter expressions are: ? IN ?, ? IS NOT IN ?, ? = ?, ? != ?, ? > ?, ? >= ?, ? < ?, ? <= ?, IS NULL and IS NOT NULL.
value number, string, boolean, array	Value to insert in the filter.

Set language, screenmode or timezone

Set language

<div id="my-dashboard"></div>

<script type="text/javascript">
  (function(d, a, s, h, b, oa, rd) {
    if (!d[b]) {oa = a.createElement(s), oa.async = 1;
    oa.src = h; rd = a.getElementsByTagName(s)[0];
    rd.parentNode.insertBefore(oa, rd);} d[b]=d[b]||{};
    d[b].addDashboard=d[b].addDashboard||function(v) {
    (d[b].list = d[b].list || []).push(v) };
  })(window, document, 'script',
    'https://cdn-a.cumul.io/js/cumulio.min.js', 'Cumulio');

  Cumulio.addDashboard({
    dashboardId: '< Dashboard id you want to embed >',
    container: '#my-dashboard',
    key: '< authorization key >',
    token: '< authorization token >'
    language: '< language code >'
  });
</script>

When you have built a multi-lingual dashboard, you can specify what language to use when integrating a dashboard in your web page.

This can be set in the addDashboard function by adding the language parameter to the function.

Parameter	Description
dashboardId uuid	This is the id of the dashboard that you want to embed.
container string	The DOM selector for identifying the container in which the dashboard will be embedded.
key uuid	The authorization id from step 1.
token string	The authorization token from step 1.
language string	en, cs, da, de, es, fi, fr, he, hu, it, ja, ko, mk, nl, pl, pt, ru, sv, zh_cn or zh_tw The language code that you wish to use in the dashboard. If that language code is not configured in the dashboard, the default language of that dashboard will be used.

For all possible parameters, check the addDashboard function in the Integration API.

Set screenmode

<div id="my-dashboard"></div>

<script type="text/javascript">
  (function(d, a, s, h, b, oa, rd) {
    if (!d[b]) {oa = a.createElement(s), oa.async = 1;
    oa.src = h; rd = a.getElementsByTagName(s)[0];
    rd.parentNode.insertBefore(oa, rd);} d[b]=d[b]||{};
    d[b].addDashboard=d[b].addDashboard||function(v) {
    (d[b].list = d[b].list || []).push(v) };
  })(window, document, 'script',
    'https://cdn-a.cumul.io/js/cumulio.min.js', 'Cumulio');

  Cumulio.addDashboard({
    dashboardId: '< Dashboard id you want to embed >',
    container: '#my-dashboard',
    key: '< authorization key >',
    token: '< authorization token >'
    screenmode: '< fixed/mobile/tablet/desktop/largeScreen/auto >'
  });
</script>

Dashboards can have multiple screenmodes and can be made responsive. This means that for a dashboard you can specify different layouts (even different charts) depending on the dashboard container size. By default, the Integration API detects the right screenmode based on the width of the container, and auto-switches to the right screenmode if it exists.

But if you specifically want to use only one screenmode, you can specify that screenmode in the addDashboard function by adding the screenmode parameter to the function.

Parameter	Description
dashboardId uuid	This is the id of the dashboard that you want to embed.
container string	The DOM selector for identifying the container in which the dashboard will be embedded.
key uuid	The authorization id. See step 1.
token string	The authorization token. See step 1.
screenmode string	fixed, mobile, tablet, desktop, largeScreen or auto. The default is 'auto'. If the screenmode is set (fixed, mobile, tablet, desktop or largeScreen) and available, that screenmode will be used. This also means that the dashboard will not auto-resize or switch to other screenmodes if the size of the container changes.

For all possible parameters, check the addDashboard function in the Integration API.

Set timezone

<div id="my-dashboard"></div>

<script type="text/javascript">
  (function(d, a, s, h, b, oa, rd) {
    if (!d[b]) {oa = a.createElement(s), oa.async = 1;
    oa.src = h; rd = a.getElementsByTagName(s)[0];
    rd.parentNode.insertBefore(oa, rd);} d[b]=d[b]||{};
    d[b].addDashboard=d[b].addDashboard||function(v) {
    (d[b].list = d[b].list || []).push(v) };
  })(window, document, 'script',
    'https://cdn-a.cumul.io/js/cumulio.min.js', 'Cumulio');

  Cumulio.addDashboard({
    dashboardId: '< Dashboard id you want to embed >',
    container: '#my-dashboard',
    key: '< authorization key >',
    token: '< authorization token >'
    timezoneId: '< timezone id >'
  });
</script>

You can override the dashboard timezone that was set in the dashboard editor when integrating a dashboard in your web page. This can be done in the addDashboard function by adding the timezoneId parameter to the function.

The provided timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York.

Parameter	Description
dashboardId uuid	This is the id of the dashboard that you want to embed.
container string	The DOM selector for identifying the container in which the dashboard will be embedded.
key uuid	The authorization id from step 1.
token string	The authorization token from step 1.
timezoneId string	Europe/Brussels, America/New_York, ...

Set loader style

When you load a page that has an embedded dashboard or chart, the dashboard first has to be retrieved from our servers. During this process, a loading indicator is shown.

This loader can be completely customized to match the styling of your website or platform.
You can change the color of the background, the color of the font, the color of the spinner itself and the background of the spinner, as well as the color of the Cumul.io logo shown at the bottom.

<div id="my-dashboard"></div>

<script type="text/javascript">
  (function(d, a, s, h, b, oa, rd) {
    if (!d[b]) {oa = a.createElement(s), oa.async = 1;
    oa.src = h; rd = a.getElementsByTagName(s)[0];
    rd.parentNode.insertBefore(oa, rd);} d[b]=d[b]||{};
    d[b].addDashboard=d[b].addDashboard||function(v) {
    (d[b].list = d[b].list || []).push(v) };
  })(window, document, 'script',
    'https://cdn-a.cumul.io/js/cumulio.min.js', 'Cumulio');

  Cumulio.addDashboard({
    dashboardId: '< Dashboard id you want to embed >',
    container: '#my-dashboard',
    key: '< authorization key >',
    token: '< authorization token >'
    loader: {
      background: '< background of the loader >',
      fontColor: '< font color of the loader >',
      spinnerColor: '< color of the spinner in the loader >',
      spinnerBackground: '< background of the spinner in the loader >',
      logoColor: '< color of the logo in the loader >'
    }
  });
</script>

These colors can be specified in three ways: hex, rgb or rgba.
For example: for the color red, the hex value is #ff0000, the rgb value is rgb(255, 0, 0) and the rgba value is rgba(255, 0, 0, 1).

Parameter	Description
dashboardId uuid	This is the id of the dashboard that containts the chart you want to embed.
container string	The DOM selector for identifying the container in which the dashboard will be embedded.
key uuid	The authorization id. See step 1.
token string	The authorization token. See step 1.
loader object	These parameters style the container while loading the dashboard.
background string	(optional) The background color (hex, rgb or rgba) of the container while loading the dashboard.
fontColor string	(optional) The font color (hex, rgb or rgba) of the messages while loading the dashboard.
spinnerColor string	(optional) The color (hex, rgb or rgba) of the spinner while loading the dashboard.
spinnerBackground string	(optional) The background (hex, rgb or rgba) of the spinner while loading the dashboard.
logoColor string	(optional) The color (hex, rgb or rgba) of our logo while loading the dashboard.

Chart integration

<div id="my-dashboard"></div>

<script type="text/javascript">
  (function(d, a, s, h, b, oa, rd) {
    if (!d[b]) {oa = a.createElement(s), oa.async = 1;
    oa.src = h; rd = a.getElementsByTagName(s)[0];
    rd.parentNode.insertBefore(oa, rd);} d[b]=d[b]||{};
    d[b].addDashboard=d[b].addDashboard||function(v) {
    (d[b].list = d[b].list || []).push(v) };
  })(window, document, 'script',
    'https://cdn-a.cumul.io/js/cumulio.min.js', 'Cumulio');

  Cumulio.addDashboard({
    dashboardId: '< Dashboard id you want to embed >',
    container: '#my-dashboard',
    key: '< authorization key >',
    token: '< authorization token >'
    chartId: '< Chart id you want to embed >'
    chartDimensions: {width: '600px', height: '400px' }
  });
</script>

It is possible to embed only a certain chart, instead of embedding the entire dashboard. To do so, you have to specify the id of the chart in the addDashboard function. Simply add the chartId parameter to the function.

By default, the chart will fill the available width of the container, and the height will be sized according to the height of the chart in your dashboard.

You can specify a fixed width and height for your chart by adding the optional chartDimensions parameter to the addDashboard function. Please refer to the table below for a more detailled explanation about setting the dimensions of a chart.

Parameter	Description
dashboardId uuid	This is the id of the dashboard that containts the chart you want to embed.
container string	The DOM selector for identifying the container in which the dashboard will be embedded.
key uuid	The authorization id. See step 1.
token string	The authorization token. See step 1.
chartId uuid	This is the id of the chart that you want to embed.
chartDimensions object	(optional) The desired dimensions of the single chart that you want to embed. By default it uses the dimensions of the chart in the dashboard. For this parameter it is required to specify a chartId.
width string	The width in pixels, e.g. 600px or auto. When auto is used, the chart will take up the available width or the container and resize when the container resizes.
height string	The height in pixels, e.g. 400px. When auto is used, the chart height will be sized according to the current screenmode of the dashboard, which is determined by the current width of the container.

For all possible parameters, check the addDashboard function in the Integration API.

Related topics

Retrieving a dashboard id

The dashboard id is a unique identifier for that dashboard.

You can retrieve the id of a dashboard in the 'settings' tab of the dashboard editor, on the right hand side of the screen.
At the bottom of the tab, you will find the dashboard id.

Retrieving a dataset id

The dataset id is a unique identifier for that dataset.

You can retrieve the id of a dataset in the 'data' tab of the dashboard editor, on the right hand side of the screen.
At the bottom of the tab, you will find the dataset id.

Retrieving a column id

The column id is a unique identifier for that column.

You can retrieve the id of a dataset column by hovering over the chart and clicking the table icon that appears next to it. You will now see an overview of all slots (columns) used in this chart. Click the gear icon next to the slot you want to know the id of, and then click the grey info circle.
At the bottom of the modal, you can find the column id. Additionally, you can also find the id of the parent dataset here.

Retrieving a chart id

The chart id is a unique identifier for that chart.

You can retrieve the id of a chart by hovering over the chart and clicking the gear icon that appears next to it. By doing this you will enter the item settings.
At the bottom of the tab, you will find the chart id.

Retrieving an account id

The account id is a unique identifier for that account. An account contains the information that is necessary to access a certain plugin or database.

You can retrieve the id of an account in the Connected accounts tab of your Profile.

Remove/replace a dashboard

It is not possible to add two or more dashboards to the same container. If you want to replace the dashboard currently embedded in a container, you have to remove it first. Then, you can add the new dashboard to that same container.

To do this, you can use the removeDashboard and addDashboard functions of the Integration API.

Invalidating tokens

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"delete",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "id": "< the authorization key to invalidate >"
  }
}
EOF

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.delete('authorization', {
  id: '< the authorization key to invalidate >'
});

You can invalidate the authorization tokens that you requested at any moment, before their specified expiry time.

For example, you could use this to invalidate all generated tokens for a user when that user clicks on the log out button on your website or platform.

Parameter	Description
id uuid	This is the id (key) of the token you want to invalidate.

Interacting with data

Connecting

Replace with your API key and token.

In curl, there is no need for an initial authentication. 
Use your API key & token in every API call.

const Cumulio = require('cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);
?>

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

To get started, please make sure you have installed and are using the correct SDK for your preferred programming language.

• Node SDK
• PHP SDK
• C# SDK
• Java SDK

You can find full-file examples for your preferred language on the GitHub pages.

For curl, there is no SDK provided, you can specify your API key and token in every curl request.

Retrieving datasets/dashboards

Retrieving all columns of a particular dataset

Replace with your own API key & token, and a valid dataset id.

curl https://api.cumul.io/0.1.0/securable \
-H "Content-Type: application/json" \
-d @- << EOF
{                                       
  "action": "get",
  "version": "0.1.0",                           
  "key": "< your API key >",    
  "token": "< your API token >",
  "find": {
    "where": {
      "id": "< your dataset id >",
      "type": "dataset"
    },
    "include":
      [{
       "model": "Column",
       "attributes": ["name", "type"]
      }],
    "attributes": ["name", "rows", "created_at"]
  }
}
EOF

const Cumulio = require('./cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

let promise = client.get('securable',
  {
    where: { 
      id: '< your dataset id >' 
      type: 'dataset'
    },
    attributes: ['name', 'rows', 'created_at'],
    include:
      [{
      model: 'Column',
      attributes: ['name', 'type']
      }],
  }
)
  .then(function (data) {
    console.log('Success!', data);
  })
  .catch(function (error) {
    console.error('API error:', error);
  })
  .finally(function () {
    client.close();
  });

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$data = $client->get('securable', array(
  'where' => array(
    'id' => '< your dataset id >'
    'type' => 'dataset',
  ),
  'attributes' => array('name', 'rows', 'created_at'),
  'include' => array(array(
    'model' => 'Column',
    'attributes' => array(
      'name',
      'type')
    ))
  )
);

print_r($data);
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private JSONObject data = client.get("securable", ImmutableMap.of(
    "where", ImmutableMap.of(
      "id", "< your dataset id >"
      "type", "dataset",
    ),
    "attributes", ImmutableList.of("name", "rows", "created_at"),
    "include", ImmutableList.of(
      ImmutableMap.of(
        "model", "Column",
        "attributes", ImmutableList.of("name", "type")
      )
    )
  )
);

System.out.println(data.toString(2));

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

filter = new ExpandoObject();
filter.where = new {
  id = "< your dataset id >",
  type = "dataset"
};
filter.attributes = new List<String> {
  "name", "rows", "created_at"
};
filter.include = new List<dynamic> {
  new {
    model = "Column",
    attributes = new List<String> {
      "name", "type"
    }
  }  
};
dynamic data = client.get("securable", filter);
Console.WriteLine(data);

This code example returns the name, number of rows and creation date of a specified dataset. Additionally, it returns the name and datatype of all its associated columns.

For an overview of all possible parameters of the dataset entity, please refer to the full specification.

For an overview of all possible parameters of the column entity, please refer to the full specification.

Parameter	Description
where object	(optional) A condition the entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response. To filter on columns of type date, pass your dates in the yyyy-MM-dd'T'HH:mm:ss.SSS format.
attributes array[string]	(optional) The attributes of the entity to be included. If this parameter is omitted, all attributes will be included in the response.
include array[object]	(optional)
model string	The name of an associated entity to be included. A full list of API entities and its associated entities can be found in the Core API section.
attributes array[string]	(optional) The attributes of the associated entity to be included in the response. If this parameter is omitted, all attributes will be included in the response.
where object	(optional) A condition the associated entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response.

Retrieving a list of all your dashboards

Replace with your own API key & token.

curl https://api.cumul.io/0.1.0/securable \
-H "Content-Type: application/json" \
-d @- << EOF
{                                       
  "action": "get",
  "version": "0.1.0",                           
  "key": "< your API key >",    
  "token": "< your API token >",
  "find": {
    "attributes": ["id", "name", "contents"],
    "include":
      [{
      "model": "Thumbnail",
      "attributes": ["url"],
      "where": {
        "size": "512px"
      }
      }],
    "type": "dashboard"
  }
}
EOF

const Cumulio = require('./cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

let promise = client.get('securable',
  {
    attributes: ['name', 'contents', 'id'],
    include: [{
        model: 'Thumbnail',
        attributes: ['url'],
        where: {
          size: '512px'
        }
      }],
    type: 'dashboard'
  }
).then(function (data) {
  console.log('Success!', data);
})
  .catch(function (error) {
    console.error('API error:', error);
  })
  .finally(function () {
    client.close();
  });

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$data = $client->get('securable', array(
  'type' => 'dashboard',
  'attributes' => array('name', 'contents', 'id'),
  'include' => array(array(
    'model' => 'Thumbnail',
    'attributes' => array('url'),
    'where' => array(
      'size' => '512px')
    ))
  )
);

print_r($data);
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private JSONObject data = client.get("securable", ImmutableMap.of(
    "type", "dashboard",
    "attributes", ImmutableList.of("name", "contents", "id"),
    "include", ImmutableList.of(
      ImmutableMap.of(
        "model", "Thumbnail",
        "attributes", ImmutableList.of("url"),
        "where", ImmutableMap.of(
          "size", "512px"
        )
      )
    )
  )
);

System.out.println(data.toString(2));

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

filter = new ExpandoObject();
filter.type = "dashboard";
filter.attributes = new List<String> {
  "name", "contents", "id"
};
filter.include = new List<dynamic> {
  new {
    model = "Thumbnail",
    attributes = new List<String> {
      "url"
    },
    where = new {
      size = "512px"
    }
  }  
};
dynamic data = client.get("securable", filter);
Console.WriteLine(data);

To retrieve a full list of a certain entity, simply omit the where parameter from your request.

In this particular example, we will use an API call to return a list of the id's, names and contents of all dashboards in your Cumul.io account.

Additionally, if applicable, for every dashboard the URL of the 512px dashboard thumbnail is added to the returned data.

This examples shows that you can also use a where specifier in the include parameter.

For an overview of all possible parameters of the dashboard entity, please refer to the full specification.

Parameter	Description
type string	The type of securable to be retrieved. Can be dashboard or dataset.
where object	(optional) A condition the entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response. To filter on columns of type date, pass your dates in the yyyy-MM-dd'T'HH:mm:ss.SSS format.
attributes array[string]	(optional) The attributes of the entity to be included. If this parameter is omitted, all attributes will be included in the response.
include array[object]	(optional)
model string	The name of an associated entity to be included. A full list of API entities and its associated entities can be found in the Core API section.
attributes array[string]	(optional) The attributes of the associated entity to be included in the response. If this parameter is omitted, all attributes will be included in the response.
where object	(optional) A condition the associated entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response.

Creating datasets automatically

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample 

JSONObject data = client.create("data",

  ImmutableMap.of(
    "type" , "create",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "Chicken baconito ",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "Quesarito",
        "3.5",
        "700",
        "menu"
      )
    ),
    "options" , ImmutableMap.of(
      "update-metadata" , "true",
      "header" , ImmutableList.of(
        "Burrito",
        "price",
        "weight",
        "order type"
      ),
      "name" , ImmutableMap.of(
        "en" , "Burritos"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample 

client.create('data',
  {
    type: 'create',
    data: [
        [
            'Chicken baconito ',
            3,
            500,
            'menu'
        ],
        [
            'Quesarito',
            3.5,
            700,
            'menu'
        ]
    ],
    options: {
        'update-metadata': 'true',
        header: [
            'Burrito',
            'price',
            'weight',
            'order type'
        ],
        name: {
            en: 'Burritos'
        }
    }
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample 

curl https://api.cumul.io/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "create",
  "data": [
    [
      "Chicken baconito ",
      3,
      500,
      "menu"
    ],
    [
      "Quesarito",
      3.5,
      700,
      "menu"
    ]
  ],
  "options": {
    "update-metadata": "true",
    "header": [
      "Burrito",
      "price",
      "weight",
      "order type"
    ],
    "name": {
      "en": "Burritos"
    }
  }
}
}
EOF

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample 

<?php
$data = $client->create('data',

  array (
    'type' => 'create',
    'data' => array (

      array (
        'Chicken baconito ',
        '3',
        '500',
        'menu'
      ),

      array (
        'Quesarito',
        '3.5',
        '700',
        'menu'
      )
    ),
    'options' => array (
      'update-metadata' => 'true',
      'header' => array (
        'Burrito',
        'price',
        'weight',
        'order type'
      ),
      'name' => array (
        'en' => 'Burritos'
      )
    )
  )

);
print("Success! { $data }");
?>

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample 

dynamic properties = new ExpandoObject();
properties.type = "create";
properties.data = new List<Object> {

      new List<Object> {
        "Chicken baconito ",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "Quesarito",
        "3.5",
        "700",
        "menu"
      }
    };
properties.options = new {
      update-metadata = "true",
      header = new List<Object> {
        "Burrito",
        "price",
        "weight",
        "order type"
      },
      name = new {
        en = "Burritos"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

It is possible in Cumul.io to create a dataset programmatically by just sending a sample the 'data' endpoint.

In order to create it, the sample will be analyzed to determine the types of the different columns. To give names to your dataset and columns there is a header and a name option provided. The code sample on the right will create a new dataset and create 4 columns. To make sure that the types are detected correctly it is advised to send a good sample for the initial creation where each column has at least a few values.

Behind the scenes, this call is creating a securable and columns. In case you want full control on the creation of securables and columns you can also create them manually by following the Creating datasets manually guide.

Creating datasets manually

Creating a new dataset

This code snippet creates a new dataset:

curl https://api.cumul.io/0.1.0/securable \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "create",
  "version": "0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties": {
      "type": "dataset",
      "name": {
        "en": "< dataset name in English >",
        "fr": "< dataset name in French >"
    },
  "description": {
    "en": "< description in English >",
    "fr": "< description in French >"
  }
 }
}
EOF

const Cumulio = require('./cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

client.create('securable',
 {
   name: {
     en: '< dataset name in English >',
     fr: '< dataset name in French >'
     // optionally add more languages here...
   },
   description: {
     en: '< dataset description in English >',
     fr: '< dataset description in French >'
     // optionally add more languages here...
   },
   type: 'dataset'
 }
)
 .then(function(dataset) {
   console.log('My new dataset id:', dataset.id);
 });

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$securable = $client->create('securable', array(
  'type' => 'dataset',
  'name' => array(
    'en' => '< dataset name in English >',
    'fr' => '< dataset name in French >'
  ),
  'description' => array(
    'en' => '< dataset description in English >',
    'fr' => '< dataset description in French >'
  )
));
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private JSONObject securable = client.create("securable", ImmutableMap.of(
  "type", "dataset",
  "name", ImmutableMap.of(
    "en", "< dataset name in English >",
    "fr", "< dataset name in French >"
  ),
  "description", ImmutableMap.of(
    "en", "< dataset description in English >",
    "fr", "< dataset description in French >"
  )
)
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "dataset";
properties.name = new {
  en = "< dataset name in English >",
  fr = "< dataset name in French >"
};
properties.description = new {
  en = "< dataset description in English >",
  fr = "< dataset description in French >"
};

dynamic securable = client.create("securable", properties);
Console.WriteLine("Dataset created with ID " + securable.id);

You can create datasets and their metadata programmatically via the API. In this case, we first build a new Securable (this is a dataset or dashboard).

The name and description are localized strings: use them to provide translations of dataset or dashboard titles, columns and other metadata. You can retrieve the most recent set languages from the locale entity.

For an explanation of the dataset entity and its possible parameters, please refer to the full specification.

Creating a column and immediately linking (associating) it with a dataset

This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset:

curl https://api.cumul.io/0.1.0/column \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "create",
  "key": "< your API key >",
  "token": "< your API token >",
  "version": "0.1.0",
  "properties": {
    "name": {
      "en": "< column name in English >",
      "fr": "< column name in French >"
    },
    "type": "hierarchy",
    "informat": "hierarchy",
    "order": 0,
    "color": "#45DE25"
  },
  "associations": [{
    "role": "Securable",
    "id": "< your dataset id >"
  }]      
}
EOF

const Cumulio = require('./cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

client.create('column',
 {
   name: {
     en: '< column name in English >',
     fr: '< column name in French >'
   },
   type: 'hierarchy',
   informat: 'hierarchy',
   order: 0,
   color: '#45DE25'
 },
 [{
   role: 'Securable',
   id: '< your dataset id >'
 }]
)
 .then(...);

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$column = $client->create('column', array(
  'name' => array(
    'en' => '< column name in English >',
    'fr' => '< column name in French >'
  ),
  'type' => 'hierarchy',
  'informat' => 'hierarchy',
  'order' => 0,
  'color' => '#45DE25'),
  array(
    array(
    'role' => 'Securable',
    'id' => '< your dataset id >'
    )
  )
);
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private JSONObject column = client.create("column", ImmutableMap.of(
  "name", ImmutableMap.of(
    "en", "< column name in English >",
    "fr", "< column name in French >"
  ),
  "type", "hierarchy",
  "informat", "hierarchy",
  "order", 0,
  "color", "#45DE25",
  ImmutableList.of(
    ImmutableMap.of(
      "role", "Securable",
      "id", "< your dataset id >"
    )
  )
)
);

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.name = new {
  en = "< column name in English >",
  fr = "< column name in French >"
};
properties.type = "hierarchy";
properties.informat = "hierarchy";
properties.order = 0;
properties.color = "#45DE25";

associations = new List<ExpandoObject>();
dynamic association = new ExpandoObject();
association.role = "Securable";
association.id = "< your dataset id >"
associations.Add(association);

dynamic column = client.create("column", properties, associations);
Console.WriteLine("Column created with ID " + column.id + " and associated.");

After you have created a dataset, it is possible to create a new column and associate it to your dataset.

For an explanation of the column entity and its possible parameters, please refer to the full specification.

Linking (associating) a dataset and a column in a seperate call

This code snippet associates the specified column with a specified dataset.

curl https://api.cumul.io/0.1.0/column \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "associate",
  "version": "0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "id": "< your column id >",  
  "resource": {
    "role": "Securable",
    "id": "< your dataset id >"
  }
}
EOF

const Cumulio = require('./cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

client.associate('securable', '< your dataset id >', {
 role: 'Columns',
 id: '< your column id >'
});

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$securable = $client->associate(
  'securable',
  '< your dataset id >',
  'Columns',
  '< your column id >');
?>

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

client.associate("column", "< your column id >", "securable", "< your dataset id >");

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

client.associate("column", "< your column id >", "securable", "< your dataset id >", new ExpandoObject());

Alternatively, you could explicitly associate both new entities at a later time.

You can do this by using the associate action on the Column entity, and specifying an instance of a Securable entity as the resource parameter.

Pushing data

   Example of appending data to an existing dataset 

JSONObject data = client.create("data",

  ImmutableMap.of(
    "securable_id" , "< Your securable id >",
    "type" , "append",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "Fresh new burrito ",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "Guacarrito",
        "3.5",
        "700",
        "menu"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Example of appending data to an existing dataset 

client.create('data',
  {
    securable_id: '< Your securable id >',
    type: 'append',
    data: [
        [
            'Fresh new burrito ',
            3,
            500,
            'menu'
        ],
        [
            'Guacarrito',
            3.5,
            700,
            'menu'
        ]
    ]
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example of appending data to an existing dataset 

curl https://api.cumul.io/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "securable_id": "< Your securable id >",
  "type": "append",
  "data": [
    [
      "Fresh new burrito ",
      3,
      500,
      "menu"
    ],
    [
      "Guacarrito",
      3.5,
      700,
      "menu"
    ]
  ]
}
}
EOF

   Example of appending data to an existing dataset 

<?php
$data = $client->create('data',

  array (
    'securable_id' => '< Your securable id >',
    'type' => 'append',
    'data' => array (

      array (
        'Fresh new burrito ',
        '3',
        '500',
        'menu'
      ),

      array (
        'Guacarrito',
        '3.5',
        '700',
        'menu'
      )
    )
  )

);
print("Success! { $data }");
?>

   Example of appending data to an existing dataset 

dynamic properties = new ExpandoObject();
properties.securable_id = "< Your securable id >";
properties.type = "append";
properties.data = new List<Object> {

      new List<Object> {
        "Fresh new burrito ",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "Guacarrito",
        "3.5",
        "700",
        "menu"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced. 

JSONObject data = client.create("data",

  ImmutableMap.of(
    "securable_id" , "< Your securable id >",
    "type" , "replace",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "New collection Guacarrito",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "New collection Quasarito",
        "3.5",
        "700",
        "menu"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced. 

client.create('data',
  {
    securable_id: '< Your securable id >',
    type: 'replace',
    data: [
        [
            'New collection Guacarrito',
            3,
            500,
            'menu'
        ],
        [
            'New collection Quasarito',
            3.5,
            700,
            'menu'
        ]
    ]
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced. 

curl https://api.cumul.io/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "securable_id": "< Your securable id >",
  "type": "replace",
  "data": [
    [
      "New collection Guacarrito",
      3,
      500,
      "menu"
    ],
    [
      "New collection Quasarito",
      3.5,
      700,
      "menu"
    ]
  ]
}
}
EOF

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced. 

<?php
$data = $client->create('data',

  array (
    'securable_id' => '< Your securable id >',
    'type' => 'replace',
    'data' => array (

      array (
        'New collection Guacarrito',
        '3',
        '500',
        'menu'
      ),

      array (
        'New collection Quasarito',
        '3.5',
        '700',
        'menu'
      )
    )
  )

);
print("Success! { $data }");
?>

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced. 

dynamic properties = new ExpandoObject();
properties.securable_id = "< Your securable id >";
properties.type = "replace";
properties.data = new List<Object> {

      new List<Object> {
        "New collection Guacarrito",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "New collection Quasarito",
        "3.5",
        "700",
        "menu"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset 

JSONObject data = client.create("data",

  ImmutableMap.of(
    "securable_id" , "< Your securable id >",
    "type" , "append",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "Fresh new burrito ",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "Guacarrito",
        "3.5",
        "700",
        "menu"
      )
    ),
    "options" , ImmutableMap.of(
      "update_metadata" , true,
      "header" , ImmutableList.of(
        "Burrito",
        "price",
        "newColumn"
      ),
      "name" , ImmutableMap.of(
        "en" , "Updated Burritos Name"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset 

client.create('data',
  {
    securable_id: '< Your securable id >',
    type: 'append',
    data: [
        [
            'Fresh new burrito ',
            3,
            500,
            'menu'
        ],
        [
            'Guacarrito',
            3.5,
            700,
            'menu'
        ]
    ],
    options: {
        update_metadata: true,
        header: [
            'Burrito',
            'price',
            'newColumn'
        ],
        name: {
            en: 'Updated Burritos Name'
        }
    }
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset 

curl https://api.cumul.io/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "securable_id": "< Your securable id >",
  "type": "append",
  "data": [
    [
      "Fresh new burrito ",
      3,
      500,
      "menu"
    ],
    [
      "Guacarrito",
      3.5,
      700,
      "menu"
    ]
  ],
  "options": {
    "update_metadata": true,
    "header": [
      "Burrito",
      "price",
      "newColumn"
    ],
    "name": {
      "en": "Updated Burritos Name"
    }
  }
}
}
EOF

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset 

<?php
$data = $client->create('data',

  array (
    'securable_id' => '< Your securable id >',
    'type' => 'append',
    'data' => array (

      array (
        'Fresh new burrito ',
        '3',
        '500',
        'menu'
      ),

      array (
        'Guacarrito',
        '3.5',
        '700',
        'menu'
      )
    ),
    'options' => array (
      'update_metadata' => true,
      'header' => array (
        'Burrito',
        'price',
        'newColumn'
      ),
      'name' => array (
        'en' => 'Updated Burritos Name'
      )
    )
  )

);
print("Success! { $data }");
?>

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset 

dynamic properties = new ExpandoObject();
properties.securable_id = "< Your securable id >";
properties.type = "append";
properties.data = new List<Object> {

      new List<Object> {
        "Fresh new burrito ",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "Guacarrito",
        "3.5",
        "700",
        "menu"
      }
    };
properties.options = new {
      update_metadata = true,
      header = new List<Object> {
        "Burrito",
        "price",
        "newColumn"
      },
      name = new {
        en = "Updated Burritos Name"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

Regardless of how you created the dataset and columns (manually or automatically) you can append or replace the data by providing the securable_id and setting the type to 'append' or 'replace' as shown in the second and third example on the right. As long as the update_metadata boolean is disabled, this will never change anything to your columns. Setting hte type to replace will replace the data in the dataset. Every row in your data parameter should have exactly the same amount of entries as there are columns in your dataset. For more information on how to find the id of a dataset, please refer to this section.

When pushing data, the dashboards that are viewing this data will be automatically brought up to date.

In case you want to automatically add/remove/update columns (use this with care), you can set the 'update_metadata' boolean to true. For example, in the third example on the right, two columns are removed and a new column is added.

Querying data

Simple example

Replace with your own API key & token, a valid dataset id and valid column id's.

curl https://api.cumul.io/0.1.0/data \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "version": "0.1.0",
  "key":  "< your API key >",
  "token": "< your API token >",
  "find": {
    "dimensions": [{
      "column_id": "Type of burrito column id",
      "dataset_id": "< your dataset id >"
    }],
    "measures": [{
      "column_id": "Number burritos savoured column id",
      "dataset_id": "< your dataset id >"
    }]
  }
}
EOF

client.query({
 dimensions: [{
   column_id: 'Type of burrito column id',
   dataset_id: '< your dataset id >'
 }],
 measures: [{
   column_id: 'Number burritos savoured column id',
   dataset_id: '< your dataset id >'
 }]
})
  .then(function(data) {
    console.log('Result set: ', data.data);
    // Prints: [['spicy', 1256],
    //          ['sweet',  913]]
  });

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$data = $client->query(
  array(
    'dimensions' => array(array(
      'column_id' => 'Type of burrito column id',
      'dataset_id' => '< your dataset id >'
    )),
    'measures' => array(array(
      'column_id' => 'Number burritos savoured column id',
      'dataset_id' => '< your dataset id >'
    ))
  )
);

print_r($data);
// Prints: [['spicy', 1256],
//          ['sweet',  913]]
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

private JSONObject data = client.query(
  ImmutableMap.of(
    "dimensions", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Type of burrito column id",
        "dataset_id", "< your dataset id >"
      )
    ),
    "measures", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Number of burritos savoured column id",
        "dataset_id", "< your dataset id >"
      )
    )
  )
);

System.out.println(data.toString(2));
// Prints: [['spicy', 1256],
//          ['sweet',  913]]

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

query = new ExpandoObject();
query.type = "dashboard";
query.dimensions = new List<dynamic> {
  new {
    column_id = "Type of burrito column id",
    dataset_id = "< your dataset id >"
  }
};
query.measures = new List<dynamic> {
  new {
    column_id = "Number burritos savoured column id",
    dataset_id = "< your dataset id >"
  }  
};

dynamic data = client.query(query);
Console.WriteLine(data);
// Prints: [['spicy', 1256],
//          ['sweet',  913]]

Just like the charts on your dashboards request data in real-time, you can interrogate your data within the platform as well.

For example, to retrieve the total number of burritos savoured per type of burrito.

Advanced example

Replace with your own API key & token, a valid dataset id and valid column id's.

curl https://api.cumul.io/0.1.0/data \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "version": "0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "find": {
    "dimensions": [{
      "column_id": "Burrito weight column id",
      "dataset_id": "< your dataset id >",
      "discretization": {
        "type": "linear",
        "size": "10"
      }
    }],
    "measures": [{
      "column_id": "Number burritos savoured column id",
      "dataset_id": "< your dataset id >"
    }],
    "where": [{
      "expression": "? = ?",
      "parameters": [{
        "column_id": "Type of burrito column id",
        "dataset_id": "< your dataset id >"
      },
      "spicy"
      ]
    }],
    "order": [{
      "column_id": "Number burritos savoured column id",
      "dataset_id": "< your dataset id >",
      "order": "desc"
    }],
    "limit": {
      "by": "5"
    }
  }
}
EOF

client.query({
 dimensions: [{
   column_id: 'Burrito weight column id',
   dataset_id: '< your dataset id >',
   discretization: {
     type: 'linear',
     size: 10
   }
 }],
 measures: [{
   column_id: 'Number burritos savoured column id',
   dataset_id: '< your dataset id >'
 }],
 where: [{
   expression: '? = ?',
   parameters: [
     {
       column_id: 'Type of burrito column id',
       dataset_id: '< your dataset id >'
     },
     'spicy'
   ]
 }],
 order: [{
   column_id: 'Number burritos savoured column id',
   dataset_id: '< your dataset id >',
   order: 'desc'
 }],
 limit: {
   by: 5
 }
})
 .then(function(data) {
   console.log('Result set:', data.data);
   // Prints: [['[ 100 - 150 [', 125],
   //            ['[ 150 - 200 [', 121]]
 });

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$data = $client->query(
  array(
    'dimensions' => array(array(
      'column_id' => 'Burrito weight id column id',
      'dataset_id' => '< your dataset id >',
      'discretization' => array(
        'type' => 'linear',
        'size' => 10
      )
    )),
    'measures' => array(array(
      'column_id' => 'Number burritos savoured column id',
      'dataset_id' => '< your dataset id >'
    )),
    'where' => array(array(
      'expression' => '? = ?',
      'parameters' => array(array(
        'column_id' => 'Type of burrito column id',
        'dataset_id' => '< your dataset id >'
      ),
      'spicy')
    )),
    'order' => array(array(
      'column_id' => 'Number burritos savoured column id',
      'dataset_id' => '< your dataset id >',
      'order' => 'desc'
    )),
    'limit' => array(
      'by' => 5
    )
  )
);

print_r($data);
// Prints: [['[ 100 - 150 [', 125],
//            ['[ 150 - 200 [', 121]]
?>

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private JSONObject data = client.query(
  ImmutableMap.of(
    "dimensions", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Burrito weight id column id",
        "dataset_id", "< your dataset id >",
        "discretization", ImmutableMap.of(
          "type", "linear",
          "size", 10
        )
      )
    ),
    "measures", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Number of burritos savoured column id",
        "dataset_id", "< your dataset id >"
      )
    ),
    "where", ImmutableList.of(
      ImmutableMap.of(
        "expression", "? = ?",
        "parameters", ImmutableList.of(
          ImmutableMap.of(
            "column_id", "Type of burrito column id",
            "dataset_id", "< your dataset id >"
          ),
          "spicy"
        )
      )
    ),
    "order", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Number of burritos savoured column id",
        "dataset_id", "< your dataset id >",
        "order", "desc"
      )
    ),
    "limit", ImmutableMap.of(
      "by", 5
    )
  )
);

System.out.println(data.toString(2));
// Prints: [['[ 100 - 150 [', 125],
//          ['[ 150 - 200 [', 121]]

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

query = new ExpandoObject();
query.type = "dashboard";
query.dimensions = new List<dynamic> {
  new {
    column_id = "Burrito weight column id",
    dataset_id = "< your dataset id >",
    discretization = new {
      type = "linear",
      size = 10
    }
  }
};
query.measures = new List<dynamic> {
  new {
    column_id = "Number burritos savoured column id",
    dataset_id = "< your dataset id >"
  }  
};
query.where = new List<dynamic> {
  new {
    expression = "? = ?",
    parameters = new List<dynamic> {
      new {
        column_id = "Type of burrito column id",
        dataset_id = "< your dataset id >"
      },
      "spicy"
    }
  }
}
query.order = new List<dynamic> {
  new {
    column_id = "Number burritos savoured column id",
    dataset_id = "< your dataset id >",
    order = "desc"
  }
}
query.limit = new {
  by = 5
}

dynamic data = client.query(query);
Console.WriteLine(data);
// Prints: [['[ 100 - 150 [', 125],
//          ['[ 150 - 200 [', 121]]

A more elaborate example: let’s record the weight per burrito as another numeric measure.

We want the weights to be classified in 10 equal sized bins, for example [50, 100[ grams, [100, 150[ grams.

Now we want to retrieve the top 5 weight classes by number of burritos savoured, but only for burritos that are of the type ‘spicy’.

External data changes

This code snippet notifies Cumul.io that a dataset has changed via an external source:

curl https://api.cumul.io/0.1.0/data \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "update",
  "version": "0.1.0",
  "key":" < your API key >",
  "token":" < your API token >",
  "id": "< your dataset id >"
}
EOF

const Cumulio = require('./cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

client.update('data', '< your dataset id >');

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);

$client->update('data', '< your dataset id >', array());
?>

import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

client.update("data", "< your dataset id >", ImmutableMap.of()));

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

client.update("data", "< your dataset id >", new ExpandoObject());

When you push data points into a dataset that is stored in Cumul.io, all dashboards are brought up-to-date immediately. To also have real-time updates to dashboards that use data providers like relational databases, you can notify Cumul.io when data changes via the Update action on the Data entity.

For example, you can do this call from within your RDBMS with a trigger on update, eg. via curl.

Core API

Introduction

This document describes the Core API which is also used by the Cumul.io application. As a client, you have access to the same API that we used to build Cumul.io. That means that you can automate everything:

• Access rights management to dashboards/datasets for users/groups/organizations.
• Loading and synchronization of datasets and setting up database connections.
• Create hierarchies or add translations for existing datasets.
• Set up automatic reporting schedules.
• Script dashboards, or use the query API to drive a custom dashboard component.

Schema

Below you can see the resources that can be accessed/created/updated/deleted via the API and how they are connected to each other:

The graph shows which resources can be associated/dissociated. When resources are associated, you can include the associated resource in a get or query request.

Actions

The core API defines actions that can be called on the resources. The api call of a specific action is standardized which means that you access each resource in a similar way. In total, 6 types of actions are defined:

Not every action is supported on every resource (e.g. you can not delete a Dataprovider). The rest of this documentation will provide information on the call signature for each action and will then go into details with concrete examples for each combination of resource and action.

Create

   Create general Signature 

JSONObject < resource name > = client.create("< resource name >",

  ImmutableMap.of(
    "attribute name" , "<attribute value>"
  ),
  ImmutableList.of(

    ImmutableMap.of(
      "role" , "<resource to link name>",
      "id" , "<resource entity id>"
    ),

    ImmutableMap.of(
      "role" , "<resource to link name>",
      "id" , "<resource entity id>"
    )
  ));
System.out.println("Success! %s%n", < resource name >);

   Create general Signature 

dynamic properties = new ExpandoObject();
properties.attribute name = "<attribute value>";

dynamic < resource name > = client.create("< resource name >",    properties);
Console.WriteLine("Success!", < resource name >);

   Create general Signature 

client.create('< resource name >',
  {
    'attribute name': '<attribute value>'
},
  [ {
    role: '<resource to link name>',
    id: '<resource entity id>'
},{
    role: '<resource to link name>',
    id: '<resource entity id>'
} ]
)
  .then(function(< resource name >) {
    console.log('Success!', < resource name >);
  });

   Create general Signature 

<?php
$< resource name > = $client->create('< resource name >',

  array (
    'attribute name' => '<attribute value>'
  ),

  array (

    array (
      'role' => '<resource to link name>',
      'id' => '<resource entity id>'
    ),

    array (
      'role' => '<resource to link name>',
      'id' => '<resource entity id>'
    )
  )
);
print("Success! { $< resource name > }");
?>

   Create general Signature 

curl https://api.cumul.io/0.1.0/< resource name >  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "attribute name": "<attribute value>"
},
  "associations": [
  {
    "role": "<resource to link name>",
    "id": "<resource entity id>"
  },
  {
    "role": "<resource to link name>",
    "id": "<resource entity id>"
  }
]
}
EOF

Create a new instance of the requested resource type, for example: create a new User within an Organization, create a new access group, create new data rows, …

Update

   Update general Signature 

JSONObject < resource name > = client.update("< resource name >", "<your < resource name > id>", 
  ImmutableMap.of(
    "attribute name" , "<attribute value>"
  ));

   Update general Signature 

dynamic properties = new ExpandoObject();
properties.attribute name = "<attribute value>";

dynamic < resource name > = client.update("< resource name >", "<your < resource name > id>", );

   Update general Signature 

client.update('< resource name >',
  '<your < resource name > id>',
  {
    'attribute name': '<attribute value>'
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Update general Signature 

<?php
$user = $client->update('< resource name >', '<your < resource name > id>', 
  array (
    'attribute name' => '<attribute value>'
  ));
?>

   Update general Signature 

curl https://api.cumul.io/0.1.0/< resource name >  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>",
  "properties": {
  "attribute name": "<attribute value>"
}
}
EOF

Update the properties of a single specific entity, eg. update a column name or user password.

Delete

   Delete general Signature 

client.delete("< resource name >", "<your < resource name > id>");

   Delete general Signature 

$client->delete("< resource name >", "<your < resource name > id>");

   Delete general Signature 

let promise = client.delete('< resource name >', '<your < resource name > id>');

   Delete general Signature 

<?php
$client->delete('< resource name >', '<your < resource name > id>');
?>

   Delete general Signature 

curl https://api.cumul.io/0.1.0/< resource name >  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>"
}
EOF

Update the properties of a single specific entity, eg. update a column name or user password.

Get & List

   Get general Signature 

JSONObject data = client.get("< resource name >", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "attribute name" , "<attribute value>"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "<resource name>"
      )
    ),
    "attributes" , ImmutableList.of(
      "<attribute name>",
      "<attribute name>"
    ),
    "order" , ImmutableList.of(

      ImmutableList.of(
        "<attribute name>",
        "asc"
      ),

      ImmutableList.of(

        ImmutableMap.of(
          "model" , "<resource name>"
        ),
        "<attribute name>",
        "asc"
      )
    )
  ));

   Get general Signature 

dynamic query = new ExpandoObject();
query.where = new {
      attribute name = "<attribute value>"
    };
query.include = new List<Object> {

      new {
        model = "<resource name>"
      }
    };
query.attributes = new List<Object> {
      "<attribute name>",
      "<attribute name>"
    };
query.order = new List<Object> {

      new List<Object> {
        "<attribute name>",
        "asc"
      },

      new List<Object> {

        new {
          model = "<resource name>"
        },
        "<attribute name>",
        "asc"
      }
    };

dynamic data = client.get("< resource name >",     query);

   Get general Signature 

client.get('< resource name >', {
    where: {
        'attribute name': '<attribute value>'
    },
    include: [
        {
            model: '<resource name>'
        }
    ],
    attributes: [
        '<attribute name>',
        '<attribute name>'
    ],
    order: [
        [
            '<attribute name>',
            'asc'
        ],
        [
            {
                model: '<resource name>'
            },
            '<attribute name>',
            'asc'
        ]
    ]
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Get general Signature 

<?php
$user = $client->get('< resource name >', 
  array (
    'where' => array (
      'attribute name' => '<attribute value>'
    ),
    'include' => array (

      array (
        'model' => '<resource name>'
      )
    ),
    'attributes' => array (
      '<attribute name>',
      '<attribute name>'
    ),
    'order' => array (

      array (
        '<attribute name>',
        'asc'
      ),

      array (

        array (
          'model' => '<resource name>'
        ),
        '<attribute name>',
        'asc'
      )
    )
  ));

?>

   Get general Signature 

curl https://api.cumul.io/0.1.0/< resource name >  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "attribute name": "<attribute value>"
  },
  "include": [
    {
      "model": "<resource name>"
    }
  ],
  "attributes": [
    "<attribute name>",
    "<attribute name>"
  ],
  "order": [
    [
      "<attribute name>",
      "asc"
    ],
    [
      {
        "model": "<resource name>"
      },
      "<attribute name>",
      "asc"
    ]
  ]
}
}
EOF

Get and List are the same call. The reason why we differentiate between a Get and a List action is that different security rules apply. A user who can get a resource can't necessarily list the same resource. Get And List have a different structure than the other calls since it allows for complex queries. A call is considered to be a get actions if you fetch an entity using a specific id in the where clause, else it is considered to be a list actions. The query syntax is very close to SQL, it consists of the following attributes:

Associate

   Associate general Signature 

client.associate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>", 
  ImmutableMap.of(
    "property name" , "<property value>"
  ) );

   Associate general Signature 

dynamic properties = new ExpandoObject();
properties.property name = "<property value>";

client.associate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>",     properties );

   Associate general Signature 

let promise = client.associate('< resource name >', '<your < resource name > id>', {
    role: '<resource to link name>',
    id: '<resource entity id>'
}, {
    'property name': '<property value>'
} );

   Associate general Signature 

<?php
$client->associate('< resource name >', '<your < resource name > id>', '<resource to link name>', '<resource entity id>', , 
  array (
    'property name' => '<property value>'
  ) );
?>

   Associate general Signature 

curl https://api.cumul.io/0.1.0/< resource name >  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>",
  "resource": {
  "role": "<resource to link name>",
  "id": "<resource entity id>"
},
  "properties": {
  "property name": "<property value>"
}
}
EOF

Associate two entities to each other, eg. link a Column to a Dataset. Associations can be set in both directions. Many associations are automatically set on creation as well, for example a dashboard is automatically associated with the user that created the dashboard. To know which resources can be associated please refer to the schema at the beginning of this chapter Schema).

Dissociate

   Dissociate general Signature 

client.dissociate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>");

   Dissociate general Signature 

client.dissociate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>");

   Dissociate general Signature 

let promise = client.dissociate('< resource name >', '<your < resource name > id>', {
    role: '<resource to link name>',
    id: '<resource entity id>'
});

   Dissociate general Signature 

<?php
$client->associate('< resource name >', '<your < resource name > id>', "<resource to link name>", "<resource entity id>");
?>

   Dissociate general Signature 

curl https://api.cumul.io/0.1.0/< resource name >  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>",
  "resource": {
  "role": "<resource to link name>",
  "id": "<resource entity id>"
}
}
EOF

Remove an association between 2 entities. To know which resources can be associated please refer to the schema at the beginning of this chapter Schema).

Connect

The API is available via WebSocket or via REST. We provide several client libraries for different languages.

Token

In order to connect you will need to retrieve your API key and API token and connect your client. You can get these here. There are multiple types of tokens: for more information on the types of tokens or how to get a token programmatically, refer to the Authorization Resource.

SDKs

   Connect to the REST API 

var Cumulio = require('cumulio');
var client = new Cumulio({
  api_key: '< your API key >',
  api_token: '< your API token >'
});

   Connect to the REST API 

include("cumulio.php");
Cumulio client = new Cumulio(
  "< your API key >",
  "< your API token >"
);

   Connect to the REST API 

<?php
include('cumulio.php');
$client = Cumulio::initialize(
  '< your API key >',
  '< your API token >'
);
?>

   Connect to the REST API 

export $CUMULIO_API_KEY="your-api-key"
export $CUMULIO_API_TOKEN="your-api-token"

curl https://api.cumul.io/0.1.0/<entity>  -H "Content-Type: application/json" -d @- << EOF
{
 "action": "<your-action>",
 "key": "$CUMULIO_API_KEY",
 "token": "$CUMULIO_API_TOKEN",
 "version": "0.1.0",
 ...
}
EOF

   Connect to the REST API 

Cumulio client = new Cumulio("< Your API key >","< Your API token >");

The libraries below are built around the REST API. The code and installation instructions for each language can be found on Github:

These libraries require a connection step where you provide the api key and token to get started. Sometimes the token has to be one for a specific user. For example binding a locale to a User requires you to be owner of that user. You can take ownership by using the login/api token of that specific user.

You can also access our API without a library using pure rest calls in which case you have to pass the api key and token on each call. For pure REST examples you can refer to the curl examples.

Resources

Authorization

Authorizations are tokens that grant access to the Cumul.io platform. Tokens can be created in a cascaded way but are always ultimately tied to a single User. Authorizations are subservient to groups and users. If a user for which you make a token has no access to a certain dashboard or dataset then an authorization token made by this user will also not have access to these resources, regardless of the filters. Of course it is possible to combine the mechanisms of groups, users and authorizations. Just like groups and users, authorizations have very powerful filters that allow filtering on the granularity of datasets/dashboards as well as at the row level of datasets.

Properties

Actions

Remember that an authorization is always immutable and therefore only supports Create, Get and Delete. It is possible though to associate using create fields which is explained further on. An authorization token can only be associated to the user that created it and is automatically associated to that User. Locale on the other hand is set using a property locale_id and cannot be updated after creation.

Action: Create

   Example of creating a technical user to start creating temporary tokens. The result will contain a Login token that you can use to request an Api token. Make sure it is added to the correct organization using the invite code so it has access to your organizations resources 

JSONObject user = client.create("user",

  ImmutableMap.of(
    "name" , "Technical User",
    "email" , "technical-user@cumul.io",
    "password" , "... random password ...",
    "invitecode" , "CJ71ySxxxx"
  ));
String login_token_key = user.getJSONObject("token").getString("id");
String login_token = user.getJSONObject("token").getString("token");

   Example of creating a technical user to start creating temporary tokens. The result will contain a Login token that you can use to request an Api token. Make sure it is added to the correct organization using the invite code so it has access to your organizations resources 

dynamic properties = new ExpandoObject();
properties.name = "Technical User";
properties.email = "technical-user@cumul.io";
properties.password = "... random password ...";
properties.invitecode = "CJ71ySxxxx";

dynamic user = client.create("user",    properties);

// The user contains a new login token
Console.WriteLine("Token Key is {0}", user["token"]["id"]);
Console.WriteLine("Token is {0}", user["token"]["token"]);

   Example of creating a technical user to start creating temporary tokens. The result will contain a Login token that you can use to request an Api token. Make sure it is added to the correct organization using the invite code so it has access to your organizations resources 

client.create('user',
  {
    name: 'Technical User',
    email: 'technical-user@cumul.io',
    password: '... random password ...',
    invitecode: 'CJ71ySxxxx'
}

)
  .then(function(user) {
    var login_token_key = user.token.id; 
var login_token = user.token.token;
  });

   Example of creating a technical user to start creating temporary tokens. The result will contain a Login token that you can use to request an Api token. Make sure it is added to the correct organization using the invite code so it has access to your organizations resources 

<?php
$user = $client->create('user',

  array (
    'name' => 'Technical User',
    'email' => 'technical-user@cumul.io',
    'password' => '... random password ...',
    'invitecode' => 'CJ71ySxxxx'
  )

);
$login_token_key = $user['token']['id'] );
 $login_token = $user['token']['token'] );
?>

   Example of creating a technical user to start creating temporary tokens. The result will contain a Login token that you can use to request an Api token. Make sure it is added to the correct organization using the invite code so it has access to your organizations resources 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": "Technical User",
  "email": "technical-user@cumul.io",
  "password": "... random password ...",
  "invitecode": "CJ71ySxxxx"
}
}
EOF
# result format of the user contains the token 
{
 ... 
 "token":{
   "uid":"9392b9d6-d182-4072-8608-17d8ff7019de",
   "id":"301ca544-b8c4-42c7-8da1-ff2d76351020",
   "token":"h1MgJq0DUR2sXxI...",
   "tokenExpiry":1534412805941,
   "cookieExpiry":"2018-08-16T09:46:45.941Z"}
...
}

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token 

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "api"
  ));
System.out.println("Success! %s%n", authorization);

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token 

dynamic properties = new ExpandoObject();
properties.type = "api";

dynamic authorization = client.create("authorization",    properties);
Console.WriteLine("Success!", authorization);

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token 

client.create('authorization',
  {
    type: 'api'
}

)
  .then(function(authorization) {
    console.log('Success!', authorization);
  });

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token 

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'api'
  )

);
print("Success! { $authorization }");
?>

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "api"
}
}
EOF

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with metadata 'username, name, email and metadata' for access logs, e.g. in this example the internal user id is set in the metadata 

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "temporary",
    "securables" , ImmutableList.of(
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ),
    "expiry" , new Date(new Date().getTime() + 2 * 3600 * 1000),
    "username" , "< end-user username >",
    "name" , "< end-user name >",
    "email" , "< end-user email >",
    "metadata" , ImmutableMap.of(
      "internalid" , "user19"
    )
  ));
System.out.println("Success! %s%n", authorization);

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with metadata 'username, name, email and metadata' for access logs, e.g. in this example the internal user id is set in the metadata 

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.securables = new List<Object> {
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
properties.expiry = DateTime.UtcNow.AddHours(2);
properties.username = "< end-user username >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.metadata = new {
      internalid = "user19"
    };

dynamic authorization = client.create("authorization",    properties);
Console.WriteLine("Success!", authorization);

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with metadata 'username, name, email and metadata' for access logs, e.g. in this example the internal user id is set in the metadata 

client.create('authorization',
  {
    type: 'temporary',
    securables: [
        '< dashboard id >',
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
    ],
    expiry: new Date(new Date().getTime() + 2 * 3600 * 1000),
    username: '< end-user username >',
    name: '< end-user name >',
    email: '< end-user email >',
    metadata: {
        internalid: 'user19'
    }
}

)
  .then(function(authorization) {
    console.log('Success!', authorization);
  });

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with metadata 'username, name, email and metadata' for access logs, e.g. in this example the internal user id is set in the metadata 

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'temporary',
    'securables' => array (
      '< dashboard id >',
      '< dataset id of a dataset used in the dashboard >',
      '< dataset id of a dataset used in the dashboard >'
    ),
    'expiry' => date("Y-m-d H:i:s", strtotime('+5 hours')),
    'username' => '< end-user username >',
    'name' => '< end-user name >',
    'email' => '< end-user email >',
    'metadata' => array (
      'internalid' => 'user19'
    )
  )

);
print("Success! { $authorization }");
?>

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with metadata 'username, name, email and metadata' for access logs, e.g. in this example the internal user id is set in the metadata 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "temporary",
  "securables": [
    "< dashboard id >",
    "< dataset id of a dataset used in the dashboard >",
    "< dataset id of a dataset used in the dashboard >"
  ],
  "expiry": "2017-08-30T14:30:15Z",
  "username": "< end-user username >",
  "name": "< end-user name >",
  "email": "< end-user email >",
  "metadata": {
    "internalid": "user19"
  }
}
}
EOF

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, e.g. in this example the Parameter "Country" is set to "Spain". Make sure to first create and set the Parameter in the dashboard.

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "temporary",
    "securables" , ImmutableList.of(
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ),
    "expiry" , new Date(new Date().getTime() + 2 * 3600 * 1000),
    "metadata" , ImmutableMap.of(
      "Country" , "Spain"
    )
  ));
System.out.println("Success! %s%n", authorization);

   Temporary token  (client created with API token) An example showing how temporary access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, e.g. in this example the Parameter "Country" is set to "Spain".  Make sure to first create and set the Parameter in the dashboard.

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.securables = new List<Object> {
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
properties.expiry = DateTime.UtcNow.AddHours(2);
properties.metadata = new {
      Country = "Spain"
    };

dynamic authorization = client.create("authorization",    properties);
Console.WriteLine("Success!", authorization);

   Temporary token  (client created with API token) An example showing how temporary access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, e.g. in this example the Parameter "Country" is set to "Spain".  Make sure to first create and set the Parameter in the dashboard.

client.create('authorization',
  {
    type: 'temporary',
    securables: [
        '< dashboard id >',
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
    ],
    expiry: new Date(new Date().getTime() + 2 * 3600 * 1000),
    metadata: {
        Country: 'Spain'
    }
}

)
  .then(function(authorization) {
    console.log('Success!', authorization);
  });

   Temporary token  (client created with API token) An example showing how temporary access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, e.g. in this example the Parameter "Country" is set to "Spain".  Make sure to first create and set the Parameter in the dashboard.

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'temporary',
    'securables' => array (
      '< dashboard id >',
      '< dataset id of a dataset used in the dashboard >',
      '< dataset id of a dataset used in the dashboard >'
    ),
    'expiry' => date("Y-m-d H:i:s", strtotime('+5 hours')),
    'metadata' => array (
      'Country' => 'Spain'
    )
  )

);
print("Success! { $authorization }");
?>

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, e.g. in this example the Parameter "Country" is set to "Spain".  Make sure to first create and set the Parameter in the dashboard.

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "temporary",
  "securables": [
    "< dashboard id >",
    "< dataset id of a dataset used in the dashboard >",
    "< dataset id of a dataset used in the dashboard >"
  ],
  "expiry": "2017-08-30T14:30:15Z",
  "metadata": {
    "Country": "Spain"
  }
}
}
EOF

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >",
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "global")
    .put("securable_id", "< dataset id of a dataset used in the dashboard >")
    .put("column_id",    "< column id of a column in a dataset used in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

   Temporary token  (client created with API token) An example showing how temporary access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "global",
    securable_id = "< dataset id of a dataset used in the dashboard >",
    column_id = "< column id of a column in a dataset used in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  filters: [
    {
      clause: 'where',
      origin: 'global',
      securable_id: '< dataset id of a dataset used in the dashboard >',
      column_id: '< column id of a column in a dataset used in the dashboard >',  
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }
  ]
});

promise.then(function(result){
  // return the result to the client
})

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard.

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'filters' => array(
    array(
      'clause'       => 'where',
      'origin'       => 'global',
      'securable_id' => '< dataset id of a dataset used in the dashboard >',
      'column_id'    => '< column id of a column in a dataset used in the dashboard >',
      'expression'   => '? = ?',
      'value'        => '< value to be applied to the expression >'
    )
  ),
));
?>

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard.

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    "filters": [
      {
        clause: "where",
        origin: "global",
        securable_id: "< dataset id of a dataset used in the dashboard >",
        column_id: "< column id of a column in a dataset used in the dashboard >",  
        expression: "? = ?",
        value: "< value to be applied to the expression >"
      }
    ]
  }
}
EOF

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >",
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "chart")
    .put("securable_id", "< dataset id of a dataset used in the dashboard >")
    .put("column_id",    "< column id of a column in a dataset used in the dashboard >")
    .put("chart_id",     "< chart id of a chart contained in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

   Temporary token  (client created with API token) An example showing how temporary access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "chart",
    securable_id = "< dataset id of a dataset used in the dashboard >",
    column_id = "< column id of a column in a dataset used in the dashboard >",
    chart_id = "< chart id of a chart contained in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  filters: [
    {
      clause: 'where',
      origin: 'chart',
      securable_id: '< dataset id of a dataset used in the dashboard >',
      column_id: '< column id of a column in a dataset used in the dashboard >',  
      chart_id: '< chart id of a chart contained in the dashboard >',
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }
  ]
});

promise.then(function(result){
  // return the result to the client
})

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'filters' => array(
    array(
      'clause'       => 'where',
      'origin'       => 'chart',
      'securable_id' => '< dataset id of a dataset used in the dashboard >',
      'column_id'    => '< column id of a column in a dataset used in the dashboard >',  
      'chart_id'     => '< chart id of a chart contained in the dashboard >',
      'expression'   => '? = ?',
      'value'        => '< value to be applied to the expression >'
    )
  ),                      
));
?>

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    "filters": [
      {
        clause: "where",
        origin: "chart",
        securable_id: "< dataset id of a dataset used in the dashboard >",
        column_id: "< column id of a column in a dataset used in the dashboard >",  
        chart_id: "< chart id of a chart contained in the dashboard >",
        expression: "? = ?",
        value: "< value to be applied to the expression >"
      }
    ]
  }
}
EOF

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with an initialization filter. An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Cumulio client = new Cumulio("< Your API key >","< Your API token >");

private Date expiry = new Date(Calendar.getInstance().getTimeInMillis() + 5*60*1000);
private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS");
private sdf.setTimeZone(TimeZone.getTimeZone("UTC"));

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","temporary")
  .put("expiry", sdf.format(expiry))
  .put("securables", ImmutableList.of(
    "< dashboard id >", 
    "< dataset id of a datased used in the dashboard >",
    "< dataset id of a datased used in the dashboard >"
  ))
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "initialization")
    .put("chart_id",     "< chart id of a chart contained in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

   Temporary token  (client created with API token) An example showing how temporary access can be granted for a user with an initialization filter. An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

Cumulio client = new Cumulio("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.expiry = DateTime.Now.AddMinutes(5);
properties.securables = new List<String> {
  "< dashboard id >", 
  "< dataset id of a datased used in the dashboard >",
  "< dataset id of a datased used in the dashboard >"
};
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "chart",
    chart_id = "< chart id of a chart contained in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with an initialization filter. An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

const Cumulio = require('cumulio');
var client = new Cumulio({
    api_key: '< Your API key >',
    api_token: '< Your API token >'
  });

let promise = client.create('authorization', {
  type: 'temporary',
  securables: [
    '< dashboard id >',
    '< dataset id of a dataset used in the dashboard >',
    '< dataset id of a dataset used in the dashboard >'
  ], 
  expiry: new Date(new Date().getTime() + 300 * 1000),
  filters: [
    {
      clause: 'where',
      origin: 'initialization',
      chart_id: '< chart id of a chart contained in the dashboard >',
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }
  ]
});

promise.then(function(result){
  // return the result to the client
})

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with an initialization filter. An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

<?php
include('cumulio.php');
$client = Cumulio::initialize('< your API key >', '< your API token >');

$authorization = $client->create('authorization', array(
  'type' => 'temporary',
  'expiry' => (new DateTime())->modify('+5 minutes')->format('c'),
  'securables' => array(
    '< dashboard id >', 
    '< dataset id of a datased used in the dashboard >',
    '< dataset id of a datased used in the dashboard >'
  ),
  'filters' => array(
    array(
      'clause'     => 'where',
      'origin'     => 'initialization',
      'chart_id'   => '< chart id of a chart contained in the dashboard >',
      'expression' => '? = ?',
      'value'      => '< value to be applied to the expression >'
    )
  ),                      
));
?>

   Temporary token (client created with API token) An example showing how temporary access can be granted for a user with an initialization filter. An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

curl https://api.cumul.io/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "temporary",
    "securables": [
      "< dashboard id >",
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    ],
    "expiry": "2018-12-31T23:59:59.999Z",
    "filters": [
      {
        clause: "where",
        origin: "initialization",
        chart_id: "< chart id of a chart contained in the dashboard >",
        expression: "? = ?",
        value: "< value to be applied to the expression >"
      }
    ]
  }
}
EOF

There are 3 types of tokens that you can create programmatically or manually:

Login tokens	These are the tokens reserved for real users when you are manually authenticating to the platform. Via the API you will only come into contact with them when you create a new user programmatically. A new user result will contain a login token, this login token can be exchanged to an API token. programmatic: the only way to create a new login token is to create a new user. Create User manual: login tokens can't be created manually
API tokens	API tokens can be used to programmatically create and update entities, push new data points or create temporary tokens programmatic: use a valid 'login' token to create an authorization token of type 'api' manual: create on the Integration management page
Temporary tokens	authorizations can be used to temporarily delegate access to one or more datasets and dashboards to a third party (for example, an end-user within your own SaaS product). They can only be created with a valid API authorization. Temporary tokens can have access restrictions to limit the range of IP addresses that can get access, which securables can be accessed, which data filters are automatically applied to all queries, ... programmatic: use a valid 'api' token to create an authorization of type 'temporary' manual: you cannot create temporary tokens via the UI

The table above shows that there are two options to get started with an API token. Either you create a new user and use the login token to get a new API token or you request an API token via the Integration management page. Temporary tokens can then be created using this API token.

Action: Get

   Retrieve all authorizations (to which you have access) that give access to a certain securable (dataset or dashboard) 

JSONObject data = client.get("authorization", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "securables" , ImmutableMap.of(
        "$contains" , "<dataset id>"
      )
    )
  ));

   Retrieve all authorizations (to which you have access) that give access to a certain securable (dataset or dashboard) 

dynamic query = new ExpandoObject();
query.where = new {
      securables = new {
        $contains = "<dataset id>"
      }
    };

dynamic data = client.get("authorization",     query);

   Retrieve all authorizations (to which you have access) that give access to a certain securable (dataset or dashboard) 

client.get('authorization', {
    where: {
        securables: {
            $contains: '<dataset id>'
        }
    }
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Retrieve all authorizations (to which you have access) that give access to a certain securable (dataset or dashboard) 

<?php
$user = $client->get('authorization', 
  array (
    'where' => array (
      'securables' => array (
        '$contains' => '<dataset id>'
      )
    )
  ));

?>

   Retrieve all authorizations (to which you have access) that give access to a certain securable (dataset or dashboard) 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "securables": {
      "$contains": "<dataset id>"
    }
  }
}
}
EOF

   Retrieve all authorization of a certain type (to which you have access) 

JSONObject data = client.get("authorization", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "type" , "api"
    )
  ));

   Retrieve all authorization of a certain type (to which you have access) 

dynamic query = new ExpandoObject();
query.where = new {
      type = "api"
    };

dynamic data = client.get("authorization",     query);

   Retrieve all authorization of a certain type (to which you have access) 

client.get('authorization', {
    where: {
        type: 'api'
    }
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Retrieve all authorization of a certain type (to which you have access) 

<?php
$user = $client->get('authorization', 
  array (
    'where' => array (
      'type' => 'api'
    )
  ));

?>

   Retrieve all authorization of a certain type (to which you have access) 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "type": "api"
  }
}
}
EOF

   Example of the return structure of an authorization. 

{
 "count": 1,
 "rows": [
    {
      "id": "c6dcefe7-a0f8-4837-9050-ba4617691a28",
      "type": "api",
      "token": "ZsLarYFbAsWBbpntli2ny5wxC5sO...",
      "expiry": "9999-12-31T00:00:00.000Z",
      "ip": null,
      "securables": null,
      "filters": null,
      "screenmode": null,
      "width": null,
      "height": null,
      "user_id": "477086f8-2ad2-4e5f-8aaf-de209f69b9bb",
      "locale_id": null,
      "last_used_at": "2018-08-13T08:29:30.000Z",
      "created_at": "2018-08-13T08:29:30.099Z",
      "updated_at": "2018-08-13T08:29:30.099Z",
      "description": null,
      "deleted_at": null,
      "username": null,
      "name": null,
      "email": null,
      "metadata": null,
      "account_overrides": null
   }
  ]
}

Authorization tokens can be fetched the same way as other resources types can be retrieved. However, you can only get the authorization tokens for which you are the entity owner (if you have created them, you are the entity owner by default), Besides of that you can not list login or temporary tokens, you can retrieve them if you know the specific id using a where clause.

Action: Delete

   Deleting an authorization 

client.delete("authorization", "<your authorization id>");

   Deleting an authorization 

$client->delete("authorization", "<your authorization id>");

   Deleting an authorization 

let promise = client.delete('authorization', '<your authorization id>');

   Deleting an authorization 

<?php
$client->delete('authorization', '<your authorization id>');
?>

   Deleting an authorization 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your authorization id>"
}
EOF

Delete is the same for each resource, the only parameters required are the resource type and the uuid of the entity you want to delete.

Associations

Authorizations are only connected to Locale and User. However, both associations are special cases since 'associate' or 'dissociate' are not available due to the immutability of authorizations.

Associate: User

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "temporary",
    "securables" , ImmutableList.of(
      "< dashboard id >"
    ),
    "locale_id" , "en"
  ));
System.out.printf("User id: %s%n", authorization.get("user_id"));

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.securables = new List<Object> {
      "< dashboard id >"
    };
properties.locale_id = "en";

dynamic authorization = client.create("authorization",    properties);

 Console.WriteLine("User id is {0}", authorization["user_id"]);

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

client.create('authorization',
  {
    type: 'temporary',
    securables: [
        '< dashboard id >'
    ],
    locale_id: 'en'
}

)
  .then(function(authorization) {
    var user = authorization.user_id;
  });

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'temporary',
    'securables' => array (
      '< dashboard id >'
    ),
    'locale_id' => 'en'
  )

);
print( $authorization['user_id'] );
?>

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "temporary",
  "securables": [
    "< dashboard id >"
  ],
  "locale_id": "en"
}
}
EOF
# result format of the authorization contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

When associating authorizations there are two things to keep in mind. First is that associations are immutable and thus the 'associate' call cannot be called directly. Secondly, the link between authorizations and users is implicit, while you can associate in the 'create' action as well, this is not possible for users. Authorizations are associated automatically. to the user who created them, you will never call the 'associate' call directly and cannot associate them to someone else than the creator.

Associate: Locale

   Example of the creation of an 'authorization' resource and immediately associating it to a locale using a locale_id 

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "temporary",
    "securables" , ImmutableList.of(
      "< dashboard id >"
    )
  ));
System.out.println("Success! %s%n", authorization);

   Example of the creation of an 'authorization' resource and immediately associating it to a locale using a locale_id 

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.securables = new List<Object> {
      "< dashboard id >"
    };

dynamic authorization = client.create("authorization",    properties);
Console.WriteLine("Success!", authorization);

   Example of the creation of an 'authorization' resource and immediately associating it to a locale using a locale_id 

client.create('authorization',
  {
    type: 'temporary',
    securables: [
        '< dashboard id >'
    ]
}

)
  .then(function(authorization) {
    console.log('Success!', authorization);
  });

   Example of the creation of an 'authorization' resource and immediately associating it to a locale using a locale_id 

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'temporary',
    'securables' => array (
      '< dashboard id >'
    )
  )

);
print("Success! { $authorization }");
?>

   Example of the creation of an 'authorization' resource and immediately associating it to a locale using a locale_id 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "temporary",
  "securables": [
    "< dashboard id >"
  ]
}
}
EOF

Connecting a locale to an authorization is implicit. Instead of creating an association, we set the locale_id directly in the properties which will create an association for us. By connecting a locale you can determine in which locale the user will see a dashboard when the token is used for embedding, to get more information on how to embed a dashboard refer to the Integration API

User

A registered Cumul.io user; note that creating new users can lead to additional charges for your current or next billing cycle. Any anonymous user or organization owner can create new users. You can only view users within your own organization. Only the user him/herself and the organization owner can view the e-mail address or update a user. Only an organization owner can delete a user.

Properties

Actions

Action: Create

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

JSONObject user = client.create("user",

  ImmutableMap.of(
    "email" , "example@cumul.io",
    "password" , "your-password",
    "name" , "Sam Examplius"
  ));
System.out.println("Success! %s%n", user);

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

dynamic properties = new ExpandoObject();
properties.email = "example@cumul.io";
properties.password = "your-password";
properties.name = "Sam Examplius";

dynamic user = client.create("user",    properties);
Console.WriteLine("Success!", user);

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

client.create('user',
  {
    email: 'example@cumul.io',
    password: 'your-password',
    name: 'Sam Examplius'
}

)
  .then(function(user) {
    console.log('Success!', user);
  });

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

<?php
$user = $client->create('user',

  array (
    'email' => 'example@cumul.io',
    'password' => 'your-password',
    'name' => 'Sam Examplius'
  )

);
print("Success! { $user }");
?>

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "email": "example@cumul.io",
  "password": "your-password",
  "name": "Sam Examplius"
}
}
EOF

   Your organization contains an invite code to add other users programmatically 

JSONObject data = client.get("organization", 
  ImmutableMap.of(

  ));
String invitecode = data.getJsonArray("rows").getJsonObject(0).getString("invitecode");

   Your organization contains an invite code to add other users programmatically 

dynamic query = new ExpandoObject();

dynamic data = client.get("organization",     query);
Console.WriteLine("Token Key is {0}", data["rows"][0]["invitecode"])

   Your organization contains an invite code to add other users programmatically 

client.get('organization', {})
  .then(function(data) {
    var invitecode = data.rows[0].invitecode;
  });

   Your organization contains an invite code to add other users programmatically 

<?php
$user = $client->get('organization', 
  array (

  ));
$invitecode = $data['rows'][0]['invitecode']
?>

   Your organization contains an invite code to add other users programmatically 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {}
}
EOF
# result format of the organization contains the invite code
    { "count": 1,
      "rows":
       [ { "id": "7a7e327a-ea93-4275-a2cc-0f21b3701abc",
       "invitecode": "tZaG4MPeRX", 
       ....

   This invite code can then be used to add users to your organization 

JSONObject user = client.create("user",

  ImmutableMap.of(
    "name" , "New user of my organization",
    "email" , "user@organization.com",
    "password" , "... random password ...",
    "invitecode" , "CJ71ySxxxx"
  ));
System.out.println("Success! %s%n", user);

   This invite code can then be used to add users to your organization 

dynamic properties = new ExpandoObject();
properties.name = "New user of my organization";
properties.email = "user@organization.com";
properties.password = "... random password ...";
properties.invitecode = "CJ71ySxxxx";

dynamic user = client.create("user",    properties);
Console.WriteLine("Success!", user);

   This invite code can then be used to add users to your organization 

client.create('user',
  {
    name: 'New user of my organization',
    email: 'user@organization.com',
    password: '... random password ...',
    invitecode: 'CJ71ySxxxx'
}

)
  .then(function(user) {
    console.log('Success!', user);
  });

   This invite code can then be used to add users to your organization 

<?php
$user = $client->create('user',

  array (
    'name' => 'New user of my organization',
    'email' => 'user@organization.com',
    'password' => '... random password ...',
    'invitecode' => 'CJ71ySxxxx'
  )

);
print("Success! { $user }");
?>

   This invite code can then be used to add users to your organization 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": "New user of my organization",
  "email": "user@organization.com",
  "password": "... random password ...",
  "invitecode": "CJ71ySxxxx"
}
}
EOF

Any new user that is created without invite code is automatically assigned to a new organization. Users can be created by anyone (even without a login token) in order to bootstrap the process to create a new organization from scratch. An organization owner can then retrieve the invite code in order to add a new user directly to the organization. This is the only way to add users to your organization, you can't associate users to organizations after their creation.

Action: Update

   Example where the password of a user is updated programmatically 

JSONObject user = client.update("user", "<your user id>", 
  ImmutableMap.of(
    "password" , "your-new-password"
  ));

   Example where the password of a user is updated programmatically 

dynamic properties = new ExpandoObject();
properties.password = "your-new-password";

dynamic user = client.update("user", "<your user id>", );

   Example where the password of a user is updated programmatically 

client.update('user',
  '<your user id>',
  {
    password: 'your-new-password'
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example where the password of a user is updated programmatically 

<?php
$user = $client->update('user', '<your user id>', 
  array (
    'password' => 'your-new-password'
  ));
?>

   Example where the password of a user is updated programmatically 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your user id>",
  "properties": {
  "password": "your-new-password"
}
}
EOF

To update a user, provide the id of the user and an object of properties which you want to overwrite. A user can update itself and an organization can update its user.

Action: Get & List

   Simple query to get a specific user 

JSONObject data = client.get("user", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "id" , "< your user id >"
    )
  ));

   Simple query to get a specific user 

dynamic query = new ExpandoObject();
query.where = new {
      id = "< your user id >"
    };

dynamic data = client.get("user",     query);

   Simple query to get a specific user 

client.get('user', {
    where: {
        id: '< your user id >'
    }
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Simple query to get a specific user 

<?php
$user = $client->get('user', 
  array (
    'where' => array (
      'id' => '< your user id >'
    )
  ));

?>

   Simple query to get a specific user 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "id": "< your user id >"
  }
}
}
EOF

   Example query that returns all securables (dashboard or dataset) that a specific user has access to either via a group or directly 

JSONObject data = client.get("user", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "id" , "< your user id >"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "group",
        "include" , ImmutableList.of(

          ImmutableMap.of(
            "model" , "securable"
          )
        )
      ),

      ImmutableMap.of(
        "model" , "securable"
      )
    )
  ));

   Example query that returns all securables (dashboard or dataset) that a specific user has access to either via a group or directly 

dynamic query = new ExpandoObject();
query.where = new {
      id = "< your user id >"
    };
query.include = new List<Object> {

      new {
        model = "group",
        include = new List<Object> {

          new {
            model = "securable"
          }
        }
      },

      new {
        model = "securable"
      }
    };

dynamic data = client.get("user",     query);

   Example query that returns all securables (dashboard or dataset) that a specific user has access to either via a group or directly 

client.get('user', {
    where: {
        id: '< your user id >'
    },
    include: [
        {
            model: 'group',
            include: [
                {
                    model: 'securable'
                }
            ]
        },
        {
            model: 'securable'
        }
    ]
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Example query that returns all securables (dashboard or dataset) that a specific user has access to either via a group or directly 

<?php
$user = $client->get('user', 
  array (
    'where' => array (
      'id' => '< your user id >'
    ),
    'include' => array (

      array (
        'model' => 'group',
        'include' => array (

          array (
            'model' => 'securable'
          )
        )
      ),

      array (
        'model' => 'securable'
      )
    )
  ));

?>

   Example query that returns all securables (dashboard or dataset) that a specific user has access to either via a group or directly 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "id": "< your user id >"
  },
  "include": [
    {
      "model": "group",
      "include": [
        {
          "model": "securable"
        }
      ]
    },
    {
      "model": "securable"
    }
  ]
}
}
EOF

   Example of the return structure of the query above 

{
  "count": 1,
  "rows": [
    {
      "email": "test-0d2b5f60@cumul.io",
      "name": "Mr Unit McTestFace",
      "city": "SmallUnitVille",
      "country_id": null,
      "locale_id": "en",
      "created_at": "2018-08-27T08:27:35.911Z",
      "id": "21f04b48-b5....",
      "groups": [
        {
          "id": "09960f12-a7....",
          "name": null,
          "public": false,
          "created_at": "2018-08-27T08:27:36.250Z",
          "updated_at": "2018-08-27T08:27:36.250Z",
          "groupRole": {
            "flagMember": true,
            "flagOwn": false,
            ...
            "user_id": "21f04b48-b544...",
            "group_id": "09960f12-a71c...."
          },
          "securables": [
            {
              "id": "26535991-03e7-4fa7-97b6-204752da6cd0",
              "type": "dataset",
              ...
              "groupAccessRight": {
                "flagRead": true,
                "flagUse": false,
                "flagModify": false,
                "flagOwn": false,
                "published": false,
                "filters": null,
                "created_at": "2018-08-27T08:27:42.121Z",
                "updated_at": "2018-08-27T08:27:42.121Z",
                "group_id": "09960f12-a71c-...",
                "securable_id": "26535991-03e..."
              }
            }
          ]
        }
      ],
      "securables": [
        {
          "id": "b7864072-ef71-4c8d...",
          "type": "dataset",
          "subtype": "api",
          "name": {
            "en": "SalesProfitCost2004.csv"
          },
          ...
          "userAccessRight": {
            "flagRead": true,
            "flagUse": false,
            ...
          }
        }
      ]
    }
  ]
}

A user can retrieve (get) itself but cannot list other users. Using the 'include' syntax you can include information on other resources which are connected to user. Organization owners can list all users of their organization and can of course get specific users as well.

Action: Delete

   An organisation owner can delete a user using the id 

client.delete("user", "<your user id>");

   An organisation owner can delete a user using the id 

$client->delete("user", "<your user id>");

   An organisation owner can delete a user using the id 

let promise = client.delete('user', '<your user id>');

   An organisation owner can delete a user using the id 

<?php
$client->delete('user', '<your user id>');
?>

   An organisation owner can delete a user using the id 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your user id>"
}
EOF

Delete a user by providing the id of the user.

Associations

Users are connected to many resources as can be seen from the partial schema.

Associate: Dashboard

   Link a user to a dashboard in order to make that dashboard readable by the user 

client.associate("securable", "<your securable id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagRead" , true
  ) );

   Link a user to a dashboard in order to make that dashboard readable by the user 

dynamic properties = new ExpandoObject();
properties.flagRead = true;

client.associate("securable", "<your securable id>", "Users", "< your user id>",     properties );

   Link a user to a dashboard in order to make that dashboard readable by the user 

let promise = client.associate('securable', '<your securable id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagRead: true
} );

   Link a user to a dashboard in order to make that dashboard readable by the user 

<?php
$client->associate('securable', '<your securable id>', 'Users', '< your user id>', , 
  array (
    'flagRead' => true
  ) );
?>

   Link a user to a dashboard in order to make that dashboard readable by the user 

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your securable id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagRead": true
}
}
EOF

   Link a user to a dashboard and give him all the rights (making him also owner of the dashboard) 

client.associate("securable", "<your securable id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagOwn" , true,
    "flagUse" , true,
    "flagModify" , true
  ) );

   Link a user to a dashboard and give him all the rights (making him also owner of the dashboard) 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagOwn = true;
properties.flagUse = true;
properties.flagModify = true;

client.associate("securable", "<your securable id>", "Users", "< your user id>",     properties );

   Link a user to a dashboard and give him all the rights (making him also owner of the dashboard) 

let promise = client.associate('securable', '<your securable id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagRead: true,
    flagOwn: true,
    flagUse: true,
    flagModify: true
} );

   Link a user to a dashboard and give him all the rights (making him also owner of the dashboard) 

<?php
$client->associate('securable', '<your securable id>', 'Users', '< your user id>', , 
  array (
    'flagRead' => true,
    'flagOwn' => true,
    'flagUse' => true,
    'flagModify' => true
  ) );
?>

   Link a user to a dashboard and give him all the rights (making him also owner of the dashboard) 

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your securable id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagRead": true,
  "flagOwn": true,
  "flagUse": true,
  "flagModify": true
}
}
EOF

A user can be linked to a dashboard to give him access to that dashboard. To start associating, note that a dashboard is a subclass of securable so we use securable in the calls. The association has flag properties to define what kind of access the user will receive. In order to start associating datasets with users, you already need to be resource owner. That means that you either created the dataset or received access from someone that associated you with the dashboard using the flagOwn = true property. That way it is possible to set multiple owners for a dashboard.

Associate: Dataset

   Link a user to a dataset in order to make that dataset readable by the user 

client.associate("securable", "<your securable id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagRead" , true
  ) );

   Link a user to a dataset in order to make that dataset readable by the user 

dynamic properties = new ExpandoObject();
properties.flagRead = true;

client.associate("securable", "<your securable id>", "Users", "< your user id>",     properties );

   Link a user to a dataset in order to make that dataset readable by the user 

let promise = client.associate('securable', '<your securable id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagRead: true
} );

   Link a user to a dataset in order to make that dataset readable by the user 

<?php
$client->associate('securable', '<your securable id>', 'Users', '< your user id>', , 
  array (
    'flagRead' => true
  ) );
?>

   Link a user to a dataset in order to make that dataset readable by the user 

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your securable id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagRead": true
}
}
EOF

   Link a user to a dataset and give him all the rights (making him also owner of the dataset) 

client.associate("securable", "<your securable id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagOwn" , true,
    "flagUse" , true,
    "flagModify" , true
  ) );

   Link a user to a dataset and give him all the rights (making him also owner of the dataset) 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagOwn = true;
properties.flagUse = true;
properties.flagModify = true;

client.associate("securable", "<your securable id>", "Users", "< your user id>",     properties );

   Link a user to a dataset and give him all the rights (making him also owner of the dataset) 

let promise = client.associate('securable', '<your securable id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagRead: true,
    flagOwn: true,
    flagUse: true,
    flagModify: true
} );

   Link a user to a dataset and give him all the rights (making him also owner of the dataset) 

<?php
$client->associate('securable', '<your securable id>', 'Users', '< your user id>', , 
  array (
    'flagRead' => true,
    'flagOwn' => true,
    'flagUse' => true,
    'flagModify' => true
  ) );
?>

   Link a user to a dataset and give him all the rights (making him also owner of the dataset) 

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your securable id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagRead": true,
  "flagOwn": true,
  "flagUse": true,
  "flagModify": true
}
}
EOF

   Link a user to a dataset, give him use rights and apply some filters 

client.associate("securable", "<your securable id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagRead", true,
    "flagUse" , true,
    "filters", ImmutableList.of(
      ImmutableMap.of(
        "clause", "where",
        "origin", "global",
        "securable_id", "< dataset id >",
        "column_id", "< column id of a column in the dataset >",
        "expression", "? = ?",
        "value", "< value to be applied to the expression >"
      )
    )
  ) 
  );

   Link a user to a dataset, give him use rights and apply some filters 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagUse = true;

properties.filters = new List<dynamic> {
  new {  
    clause = "where";
    origin = "global";
    securable_id = "< dataset id >";
    column_id = "< column id of a column in the dataset >";
    expression = "? = ?";
    value = "< value to be applied to the expression >";
  }
};

client.associate("securable", "<your securable id>", "Users", "< your user id>",   properties );

   Link a user to a dataset, give him use rights and apply some filters

let promise = client.associate('securable', '<your securable id>', {
  role: 'Users',
  id: '< your user id>'
}, {
  flagRead: true,
  flagUse: true,
  filters: [
    {
      clause: 'where',
      origin: 'global',
      securable_id: '< dataset id >',
      column_id: '< column id of a column used in the dataset >',  
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }  
  ]
} );

   Link a user to a dataset, give him use rights and apply some filters 

<?php
$client->associate('securable', '<your securable id>', 'Users', '< your user id>', , 
  array (
    'flagRead' => true,
    'flagUse' => true,
    'filters' => array(
      'clause'       => 'where',
      'origin'       => 'global',
      'securable_id' => '< dataset id >',
      'column_id'    => '< column id of a column used in the dataset >',
      'expression'   => '? = ?',
      'value'        => '< value to be applied to the expression >'
    )
  ) );
?>

   Link a user to a dataset, give him use rights and apply some filters

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your securable id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagRead": true,
  "flagUse": true,
  "filters": [
      {
        "clause": "where",
        "origin": "global",
        "securable_id": "< dataset id >",
        "column_id": "< column id of a column used in the dataset >",  
        "expression": "? = ?",
        "value": "< value to be applied to the expression >"
      }
    ]
}
}
EOF

A user can be linked to a securable to give him access to that dataset. To start associating, note that a dataset is a subclass of securable so we use securable in the calls. The association has flag properties to define what kind of access the user will receive. In order to start associating dashboards with users, you already need to be resource owner. That means that you either created the dashboard or received access from someone that associated you with the dashboard using the flagOwn = true property. That way it is possible to set multiple owners for a dataset. In additon to setting ownership properties, you can supply filters when associating a dataset to a user. When a user opens or uses the dataset, these filters will be applied. The syntax is identical to creating an authorization with filters.

Associate: Group

   Link a user to a group and set him as member of that group 

client.associate("group", "<your group id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagMember" , true,
    "flagOwn" , false
  ) );

   Link a user to a group and set him as member of that group 

dynamic properties = new ExpandoObject();
properties.flagMember = true;
properties.flagOwn = false;

client.associate("group", "<your group id>", "Users", "< your user id>",     properties );

   Link a user to a group and set him as member of that group 

let promise = client.associate('group', '<your group id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagMember: true,
    flagOwn: false
} );

   Link a user to a group and set him as member of that group 

<?php
$client->associate('group', '<your group id>', 'Users', '< your user id>', , 
  array (
    'flagMember' => true,
    'flagOwn' => false
  ) );
?>

   Link a user to a group and set him as member of that group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagMember": true,
  "flagOwn": false
}
}
EOF

Groups can be used to give a group of users access to securables (dashboards or datasets). When associating a user with a group there are flags available that describe the kind of relation. Adding a user in a group without setting any flags will not have any effect. Only the owner of a group can add members to the group. The user who created the group automatically becomes an owner of the group.

Associate: Locale

   Set the default language (locale) of the user. Datasets and dashboards will initially open with this selected language. 

client.associate("locale", "<your locale id>", "Users", "< your user id>");

   Set the default language (locale) of the user. Datasets and dashboards will initially open with this selected language. 

client.associate("locale", "<your locale id>", "Users", "< your user id>");

   Set the default language (locale) of the user. Datasets and dashboards will initially open with this selected language. 

let promise = client.associate('locale', '<your locale id>', {
    role: 'Users',
    id: '< your user id>'
});

   Set the default language (locale) of the user. Datasets and dashboards will initially open with this selected language. 

<?php
$client->associate('locale', '<your locale id>', 'Users', '< your user id>', );
?>

   Set the default language (locale) of the user. Datasets and dashboards will initially open with this selected language. 

curl https://api.cumul.io/0.1.0/locale  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your locale id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
}
}
EOF

Set the default language (locale) of the user. Datasets and dashboards will initially open with this selected language. The locale of the user needs to be changed by the entity owner. If you need to set the locale manually for each user you can use the login token when you created them to fetch an API token and set the locale for him.

Associate: Organization

   Your organization contains an invite code to add other users programmatically 

JSONObject data = client.get("organization", 
  ImmutableMap.of(

  ));
String invitecode = data.getJsonArray("rows").getJsonObject(0).getString("invitecode");

   Your organization contains an invite code to add other users programmatically 

dynamic query = new ExpandoObject();

dynamic data = client.get("organization",     query);
Console.WriteLine("Token Key is {0}", data["rows"][0]["invitecode"])

   Your organization contains an invite code to add other users programmatically 

client.get('organization', {})
  .then(function(data) {
    var invitecode = data.rows[0].invitecode;
  });

   Your organization contains an invite code to add other users programmatically 

<?php
$user = $client->get('organization', 
  array (

  ));
$invitecode = $data['rows'][0]['invitecode']
?>

   Your organization contains an invite code to add other users programmatically 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {}
}
EOF
# result format of the organization contains the invite code
    { "count": 1,
      "rows":
       [ { "id": "7a7e327a-ea93-4275-a2cc-0f21b3701abc",
       "invitecode": "tZaG4MPeRX", 
       ....

   This invite code can then be used to add users to your organization 

JSONObject user = client.create("user",

  ImmutableMap.of(
    "name" , "New user of my organization",
    "email" , "user@organization.com",
    "password" , "... random password ...",
    "invitecode" , "CJ71ySxxxx"
  ));
System.out.println("Success! %s%n", user);

   This invite code can then be used to add users to your organization 

dynamic properties = new ExpandoObject();
properties.name = "New user of my organization";
properties.email = "user@organization.com";
properties.password = "... random password ...";
properties.invitecode = "CJ71ySxxxx";

dynamic user = client.create("user",    properties);
Console.WriteLine("Success!", user);

   This invite code can then be used to add users to your organization 

client.create('user',
  {
    name: 'New user of my organization',
    email: 'user@organization.com',
    password: '... random password ...',
    invitecode: 'CJ71ySxxxx'
}

)
  .then(function(user) {
    console.log('Success!', user);
  });

   This invite code can then be used to add users to your organization 

<?php
$user = $client->create('user',

  array (
    'name' => 'New user of my organization',
    'email' => 'user@organization.com',
    'password' => '... random password ...',
    'invitecode' => 'CJ71ySxxxx'
  )

);
print("Success! { $user }");
?>

   This invite code can then be used to add users to your organization 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": "New user of my organization",
  "email": "user@organization.com",
  "password": "... random password ...",
  "invitecode": "CJ71ySxxxx"
}
}
EOF

The link between Organizations and Users is also a special case. You can't add users to an organization once the users are made. The only way to add users to an organization is on creation time by using an invite code. As shown in the code samples, the invitecode can be retrieved by getting your organization through the API.

If you use a correct invite code, the association between the organization and user will be made implicitely. Later on you can fetch the users of your organization using the 'include' syntax in a get call.

Associate: Country

   Set the country of residence for a user 

client.associate("country", "<your country id>", "Users", "< your user id>");

   Set the country of residence for a user 

client.associate("country", "<your country id>", "Users", "< your user id>");

   Set the country of residence for a user 

let promise = client.associate('country', '<your country id>', {
    role: 'Users',
    id: '< your user id>'
});

   Set the country of residence for a user 

<?php
$client->associate('country', '<your country id>', 'Users', '< your user id>', );
?>

   Set the country of residence for a user 

curl https://api.cumul.io/0.1.0/country  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your country id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
}
}
EOF

Users can be associated to countries. This simply informs the platform on the country of residence of the user. Countries can also be associated to organizations which serve as a default for the users of that organization. Just like locale, a country associated with user directly will take priority.

Associate: Account (implicit)

   Accounts are linked to users on creation 

JSONObject account = client.create("account",

  ImmutableMap.of(
    "provider" , "postgresql",
    "host" , "<host address / ip>",
    "port" , "5432",
    "scope" , "<your database name>",
    "identifier" , "<username>",
    "token" , "<password>"
  ));
System.out.printf("User id: %s%n", account.get("user_id"));

   Accounts are linked to users on creation 

dynamic properties = new ExpandoObject();
properties.provider = "postgresql";
properties.host = "<host address / ip>";
properties.port = "5432";
properties.scope = "<your database name>";
properties.identifier = "<username>";
properties.token = "<password>";

dynamic account = client.create("account",    properties);

 Console.WriteLine("User id is {0}", account["user_id"]);

   Accounts are linked to users on creation 

client.create('account',
  {
    provider: 'postgresql',
    host: '<host address / ip>',
    port: 5432,
    scope: '<your database name>',
    identifier: '<username>',
    token: '<password>'
}

)
  .then(function(account) {
    var user = account.user_id;
  });

   Accounts are linked to users on creation 

<?php
$account = $client->create('account',

  array (
    'provider' => 'postgresql',
    'host' => '<host address / ip>',
    'port' => '5432',
    'scope' => '<your database name>',
    'identifier' => '<username>',
    'token' => '<password>'
  )

);
print( $account['user_id'] );
?>

   Accounts are linked to users on creation 

curl https://api.cumul.io/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "provider": "postgresql",
  "host": "<host address / ip>",
  "port": 5432,
  "scope": "<your database name>",
  "identifier": "<username>",
  "token": "<password>"
}
}
EOF
# result format of the account contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

This is a special case similar to many entities that are linked to user. The association to the creating user is automatically added when a new account is created.

Associate: Authorization (implicit)

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "temporary",
    "securables" , ImmutableList.of(
      "< dashboard id >"
    ),
    "locale_id" , "en"
  ));
System.out.printf("User id: %s%n", authorization.get("user_id"));

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

dynamic properties = new ExpandoObject();
properties.type = "temporary";
properties.securables = new List<Object> {
      "< dashboard id >"
    };
properties.locale_id = "en";

dynamic authorization = client.create("authorization",    properties);

 Console.WriteLine("User id is {0}", authorization["user_id"]);

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

client.create('authorization',
  {
    type: 'temporary',
    securables: [
        '< dashboard id >'
    ],
    locale_id: 'en'
}

)
  .then(function(authorization) {
    var user = authorization.user_id;
  });

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'temporary',
    'securables' => array (
      '< dashboard id >'
    ),
    'locale_id' => 'en'
  )

);
print( $authorization['user_id'] );
?>

   newly created associations are immediately associated with the user that created them, the response contains the user_id, this is the only way to associate users 

curl https://api.cumul.io/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "temporary",
  "securables": [
    "< dashboard id >"
  ],
  "locale_id": "en"
}
}
EOF
# result format of the authorization contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

When associating authorizations there are two things to keep in mind. First is that associations are immutable and thus the 'associate' call cannot be called directly. Secondly, the link between authorizations and users is implicit, while you can associate in the 'create' action as well, this is not possible for users. Authorizations are associated automatically. to the user who created them, you will never call the 'associate' call directly and cannot associate them to someone else than the creator.

Associate: Schedule (implicit)

   Schedules are automatically linked to the user who created them 

JSONObject schedule = client.create("schedule",

  ImmutableMap.of(
    "type" , "dataset",
    "started_at" , "startDate",
    "frequency" , "1440",
    "scheduled_at" , new Date();,
    "completed_at" , new Date();,
    "active" , true
  ));
System.out.printf("User id: %s%n", schedule.get("user_id"));

   Schedules are automatically linked to the user who created them 

dynamic properties = new ExpandoObject();
properties.type = "dataset";
properties.started_at = "startDate";
properties.frequency = "1440";
properties.scheduled_at = DateTime.UtcNow;
properties.completed_at = DateTime.UtcNow;
properties.active = true;

dynamic schedule = client.create("schedule",    properties);

 Console.WriteLine("User id is {0}", schedule["user_id"]);

   Schedules are automatically linked to the user who created them 

client.create('schedule',
  {
    type: 'dataset',
    started_at: 'startDate',
    frequency: 1440,
    scheduled_at: new Date(),
    completed_at: '<!new Date()!>',
    active: true
}

)
  .then(function(schedule) {
    var user = schedule.user_id;
  });

   Schedules are automatically linked to the user who created them 

<?php
$schedule = $client->create('schedule',

  array (
    'type' => 'dataset',
    'started_at' => 'startDate',
    'frequency' => '1440',
    'scheduled_at' => date("Y-m-d H:i:s"),
    'completed_at' => date("Y-m-d H:i:s"),
    'active' => true
  )

);
print( $schedule['user_id'] );
?>

   Schedules are automatically linked to the user who created them 

curl https://api.cumul.io/0.1.0/schedule  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "dataset",
  "started_at": "startDate",
  "frequency": 1440,
  "scheduled_at": "2017-08-30T14:30:15Z",
  "completed_at": "2017-08-30T14:30:15Z",
  "active": true
}
}
EOF
# result format of the schedule contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

This is a special case similar to many entities that are linked to user. The association to the creating user is created automatically when a schedule is made, this association cannot be created manually. The user that created the schedule is the only one who can get, delete, update, associate or dissociate this schedule

Associate: Plugin (implicit)

   A plugin is automatically bound to the creating user on creation, that user is the Entity Owner and is the only one who can change the plugin 

JSONObject plugin = client.create("plugin",

  ImmutableMap.of(
    "slug" , "myplugin",
    "name" , ImmutableMap.of(
      "en" , "My Internal Api Plugin"
    ),
    "description" , ImmutableMap.of(
      "en" , "Since we already have an API, we wrote a simple plugin around our API"
    ),
    "base_url" , "https://my-company.com/data/api/v1",
    "url" , "https://my-company.com/info",
    "secret" , "<cumulio-secret>",
    "authorize" , "token",
    "color" , "#00FF00",
    "pushdown" , false
  ));
System.out.printf("User id: %s%n", plugin.get("user_id"));

   A plugin is automatically bound to the creating user on creation, that user is the Entity Owner and is the only one who can change the plugin 

dynamic properties = new ExpandoObject();
properties.slug = "myplugin";
properties.name = new {
      en = "My Internal Api Plugin"
    };
properties.description = new {
      en = "Since we already have an API, we wrote a simple plugin around our API"
    };
properties.base_url = "https://my-company.com/data/api/v1";
properties.url = "https://my-company.com/info";
properties.secret = "<cumulio-secret>";
properties.authorize = "token";
properties.color = "#00FF00";
properties.pushdown = false;

dynamic plugin = client.create("plugin",    properties);

 Console.WriteLine("User id is {0}", plugin["user_id"]);

   A plugin is automatically bound to the creating user on creation, that user is the Entity Owner and is the only one who can change the plugin 

client.create('plugin',
  {
    slug: 'myplugin',
    name: {
        en: 'My Internal Api Plugin'
    },
    description: {
        en: 'Since we already have an API, we wrote a simple plugin around our API'
    },
    base_url: 'https://my-company.com/data/api/v1',
    url: 'https://my-company.com/info',
    secret: '<cumulio-secret>',
    authorize: 'token',
    color: '#00FF00',
    pushdown: false
}

)
  .then(function(plugin) {
    var user = plugin.user_id;
  });

   A plugin is automatically bound to the creating user on creation, that user is the Entity Owner and is the only one who can change the plugin 

<?php
$plugin = $client->create('plugin',

  array (
    'slug' => 'myplugin',
    'name' => array (
      'en' => 'My Internal Api Plugin'
    ),
    'description' => array (
      'en' => 'Since we already have an API, we wrote a simple plugin around our API'
    ),
    'base_url' => 'https://my-company.com/data/api/v1',
    'url' => 'https://my-company.com/info',
    'secret' => '<cumulio-secret>',
    'authorize' => 'token',
    'color' => '#00FF00',
    'pushdown' => false
  )

);
print( $plugin['user_id'] );
?>

   A plugin is automatically bound to the creating user on creation, that user is the Entity Owner and is the only one who can change the plugin 

curl https://api.cumul.io/0.1.0/plugin  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "slug": "myplugin",
  "name": {
    "en": "My Internal Api Plugin"
  },
  "description": {
    "en": "Since we already have an API, we wrote a simple plugin around our API"
  },
  "base_url": "https://my-company.com/data/api/v1",
  "url": "https://my-company.com/info",
  "secret": "<cumulio-secret>",
  "authorize": "token",
  "color": "#00FF00",
  "pushdown": false
}
}
EOF
# result format of the plugin contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

This is a special case similar to many entities that are linked to user. The association to the creating user is automatically added when a plugin is created, this association cannot be created manually. The user that created the schedule is the owner of the Plugin and the only one who can manipulate the plugin.

Associate: Share (implicit)

   Shares don't require parameters and are immediately linked to a user on creation 

JSONObject share = client.create("share",

  ImmutableMap.of(

  ));
System.out.printf("User id: %s%n", share.get("user_id"));

   Shares don't require parameters and are immediately linked to a user on creation 

dynamic properties = new ExpandoObject();

dynamic share = client.create("share",    properties);

 Console.WriteLine("User id is {0}", share["user_id"]);

   Shares don't require parameters and are immediately linked to a user on creation 

client.create('share',
  {}

)
  .then(function(share) {
    var user = share.user_id;
  });

   Shares don't require parameters and are immediately linked to a user on creation 

<?php
$share = $client->create('share',

  array (

  )

);
print( $share['user_id'] );
?>

   Shares don't require parameters and are immediately linked to a user on creation 

curl https://api.cumul.io/0.1.0/share  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {}
}
EOF
# result format of the share contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

This is a special case similar to many entities that are linked to user. When creating a private link to a dashboard, the creating user is automatically linked to the Share. Note that the code on the right only creates a link which is not yet linked to a dashboard.

Dissociate

   Example query that removes a user from a group 

client.dissociate("user", "<your user id>", "Groups", "<group id>");

   Example query that removes a user from a group 

client.dissociate("user", "<your user id>", "Groups", "<group id>");

   Example query that removes a user from a group 

let promise = client.dissociate('user', '<your user id>', {
    role: 'Groups',
    id: '<group id>'
});

   Example query that removes a user from a group 

<?php
$client->associate('user', '<your user id>', "Groups", "<group id>");
?>

   Example query that removes a user from a group 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your user id>",
  "resource": {
  "role": "Groups",
  "id": "<group id>"
}
}
EOF

   Example query that removes a user from a group 

client.dissociate("group", "<your group id>", "Users", "<user id>");

   Example query that removes a user from a group 

client.dissociate("group", "<your group id>", "Users", "<user id>");

   Example query that removes a user from a group 

let promise = client.dissociate('group', '<your group id>', {
    role: 'Users',
    id: '<user id>'
});

   Example query that removes a user from a group 

<?php
$client->associate('group', '<your group id>', "Users", "<user id>");
?>

   Example query that removes a user from a group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Users",
  "id": "<user id>"
}
}
EOF

Dissociating is similar for all resources. To break the link between two resources, simply provide the resource names and ids. Be careful that the 'role' of a resource is uppercase and usually plural. Dissociating can be done in both directions.

Group

Division or group within or across the bounds of organizations. Groups have administrators and members and can be assigned access rights to datasets or dashboards.

The creating user of a group is automatically given group owner rights. Groups can be created by any user. Only group owners can update or delete a group, or associate or dissociate new group members.

Properties

Actions

Action: Create

   Creating a group 

JSONObject group = client.create("group",

  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "< group name in English ›",
      "fr" , "< group name in French >"
    )
  ));
System.out.println("Success! %s%n", group);

   Creating a group 

dynamic properties = new ExpandoObject();
properties.name = new {
      en = "< group name in English ›",
      fr = "< group name in French >"
    };

dynamic group = client.create("group",    properties);
Console.WriteLine("Success!", group);

   Creating a group 

client.create('group',
  {
    name: {
        en: '< group name in English ›',
        fr: '< group name in French >'
    }
}

)
  .then(function(group) {
    console.log('Success!', group);
  });

   Creating a group 

<?php
$group = $client->create('group',

  array (
    'name' => array (
      'en' => '< group name in English ›',
      'fr' => '< group name in French >'
    )
  )

);
print("Success! { $group }");
?>

   Creating a group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": {
    "en": "< group name in English ›",
    "fr": "< group name in French >"
  }
}
}
EOF

Any user with an API token can create a group. The group will be automatically linked to the user on creation (which will be the group owner). Creating a group does not necessarily require parameters but you can provide the group with a name. The name will be used in the interface.

Action: Update

   Updating a group 

JSONObject group = client.update("group", "<your group id>", 
  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "< new group name in English >",
      "fr" , "< new group name in French >"
    )
  ));

   Updating a group 

dynamic properties = new ExpandoObject();
properties.name = new {
      en = "< new group name in English >",
      fr = "< new group name in French >"
    };

dynamic group = client.update("group", "<your group id>", );

   Updating a group 

client.update('group',
  '<your group id>',
  {
    name: {
        en: '< new group name in English >',
        fr: '< new group name in French >'
    }
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Updating a group 

<?php
$user = $client->update('group', '<your group id>', 
  array (
    'name' => array (
      'en' => '< new group name in English >',
      'fr' => '< new group name in French >'
    )
  ));
?>

   Updating a group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "properties": {
  "name": {
    "en": "< new group name in English >",
    "fr": "< new group name in French >"
  }
}
}
EOF

Only the owner of the group can update the group. Other users can be made owner by associating them with the group and using the 'flagOwner'.

Action: Get

   Getting a group together with its users and the securables it gives access to (Dashboards/Datasets) 

JSONObject data = client.get("group", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "id" , "<your group id>"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "User"
      ),

      ImmutableMap.of(
        "model" , "Securable"
      )
    )
  ));

   Getting a group together with its users and the securables it gives access to (Dashboards/Datasets) 

dynamic query = new ExpandoObject();
query.where = new {
      id = "<your group id>"
    };
query.include = new List<Object> {

      new {
        model = "User"
      },

      new {
        model = "Securable"
      }
    };

dynamic data = client.get("group",     query);

   Getting a group together with its users and the securables it gives access to (Dashboards/Datasets) 

client.get('group', {
    where: {
        id: '<your group id>'
    },
    include: [
        {
            model: 'User'
        },
        {
            model: 'Securable'
        }
    ]
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Getting a group together with its users and the securables it gives access to (Dashboards/Datasets) 

<?php
$user = $client->get('group', 
  array (
    'where' => array (
      'id' => '<your group id>'
    ),
    'include' => array (

      array (
        'model' => 'User'
      ),

      array (
        'model' => 'Securable'
      )
    )
  ));

?>

   Getting a group together with its users and the securables it gives access to (Dashboards/Datasets) 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "id": "<your group id>"
  },
  "include": [
    {
      "model": "User"
    },
    {
      "model": "Securable"
    }
  ]
}
}
EOF

   Example of the return structure of the query above 

{
   "count": 1,
   "rows": [
     {
       "id": "f5aff911-94fc-45f3-9de2-68e3a0a82334",
       "name": {
         "en": "MyGroup"
       },
       "created_at": "2018-08-28T10:12:23.625Z",
       "updated_at": "2018-08-28T10:12:23.625Z",
       "deleted_at": null,
       "public": false,
       "open": false,
       "users": [
         {
           "email": "someuser1@cumul.io",
           "name": "Mr Unit McTestFace",
           "city": "SmallUnitVille",
           "country_id": null,
           "locale_id": "en",
           "created_at": "2018-08-28T10:12:22.563Z",
           "id": "a7a900a2-b14e-49cc-94ea-7b034407be86",
           "groupRole": {
             "flagMember": true,
             "flagOwn": true,
             "created_at": "2018-08-28T10:12:23.631Z",
             "updated_at": "2018-08-28T10:12:23.631Z",
             "user_id": "a7a900a2-b14e-49cc-94ea-7b034407be86",
             "group_id": "f5aff911-94fc-45f3-9de2-68e3a0a82334"
           }
         },
         {
           "email": "someuser2@cumul.io",
           ...
           "groupRole": {
             "flagMember": true,
             "flagOwn": false,
             ....
           }
         },
         {
           "email": "someuser3@cumul.io",
           ....
           "groupRole": {
             "flagMember": true,
             "flagOwn": false,
             ...
           }
         }
       ],
       "securables": [
         {
           "id": "c5f4a9ab-bace-485e-aeeb-a89ea76502b5",
           "type": "dataset",
           "subtype": "api",
           "name": {
             "en": "SalesProfitCost2004.csv"
           },
           "description": null,
           ...
           "modifier_id": "a7a900a2-b14e-49cc-94ea-7b034407be86",
           "owner_id": "a7a900a2-b14e-49cc-94ea-7b034407be86",
           "groupAccessRight": {
             "flagRead": true,
             "flagUse": false,
             ...
             "published": false,
             "filters": null,
             ...
             "group_id": "f5aff911-94fc-...",
             "securable_id": "17866361-79f..."
           }
         },
         {
           "id": "17866361-79f7-4268-ba9f-a2eb5facd01d",
           ...
           "groupAccessRight": {
             ...
           }
         }
       ]
     }
   ]
 }

Groups can only be retrieved by group members or owner. They are linked to Securables (Dashboard/Dataset) and users which can be included in the results. For example we could do a query to get all members of a group or retrieve all securables that a group has access to. Note that you will only receive the included entities to which you have access, for example you will only receive users in the group that are in your organization. Although you can add users outside of your organization to a group, you can not list their details.

Action: Delete

   Delete a group using the id 

client.delete("group", "<your group id>");

   Delete a group using the id 

$client->delete("group", "<your group id>");

   Delete a group using the id 

let promise = client.delete('group', '<your group id>');

   Delete a group using the id 

<?php
$client->delete('group', '<your group id>');
?>

   Delete a group using the id 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>"
}
EOF

Delete a group by providing the id of the group.

Associations

Groups are only connected to securables and users.

Associate: Dashboard

   Link a user to a group and set him as member of that group 

client.associate("group", "<your group id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagMember" , true,
    "flagOwn" , false
  ) );

   Link a user to a group and set him as member of that group 

dynamic properties = new ExpandoObject();
properties.flagMember = true;
properties.flagOwn = false;

client.associate("group", "<your group id>", "Users", "< your user id>",     properties );

   Link a user to a group and set him as member of that group 

let promise = client.associate('group', '<your group id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagMember: true,
    flagOwn: false
} );

   Link a user to a group and set him as member of that group 

<?php
$client->associate('group', '<your group id>', 'Users', '< your user id>', , 
  array (
    'flagMember' => true,
    'flagOwn' => false
  ) );
?>

   Link a user to a group and set him as member of that group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagMember": true,
  "flagOwn": false
}
}
EOF

   Link a group to a securable, and give read/use/write access to that group 

client.associate("group", "<your group id>", "Securables", "< your securable (dashboard or dataset) id>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagModify" , true,
    "flagUse" , true,
    "flagOwn" , false
  ) );

   Link a group to a securable, and give read/use/write access to that group 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagModify = true;
properties.flagUse = true;
properties.flagOwn = false;

client.associate("group", "<your group id>", "Securables", "< your securable (dashboard or dataset) id>",     properties );

   Link a group to a securable, and give read/use/write access to that group 

let promise = client.associate('group', '<your group id>', {
    role: 'Securables',
    id: '< your securable (dashboard or dataset) id>'
}, {
    flagRead: true,
    flagModify: true,
    flagUse: true,
    flagOwn: false
} );

   Link a group to a securable, and give read/use/write access to that group 

<?php
$client->associate('group', '<your group id>', 'Securables', '< your securable (dashboard or dataset) id>', , 
  array (
    'flagRead' => true,
    'flagModify' => true,
    'flagUse' => true,
    'flagOwn' => false
  ) );
?>

   Link a group to a securable, and give read/use/write access to that group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Securables",
  "id": "< your securable (dashboard or dataset) id>"
},
  "properties": {
  "flagRead": true,
  "flagModify": true,
  "flagUse": true,
  "flagOwn": false
}
}
EOF

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

client.associate("group", "<your group id>", "Securables", "< id of the public group>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagModify" , false,
    "flagUse" , false,
    "flagOwn" , false,
    "published" , false
  ) );

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagModify = false;
properties.flagUse = false;
properties.flagOwn = false;
properties.published = false;

client.associate("group", "<your group id>", "Securables", "< id of the public group>",     properties );

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

let promise = client.associate('group', '<your group id>', {
    role: 'Securables',
    id: '< id of the public group>'
}, {
    flagRead: true,
    flagModify: false,
    flagUse: false,
    flagOwn: false,
    published: false
} );

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

<?php
$client->associate('group', '<your group id>', 'Securables', '< id of the public group>', , 
  array (
    'flagRead' => true,
    'flagModify' => false,
    'flagUse' => false,
    'flagOwn' => false,
    'published' => false
  ) );
?>

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Securables",
  "id": "< id of the public group>"
},
  "properties": {
  "flagRead": true,
  "flagModify": false,
  "flagUse": false,
  "flagOwn": false,
  "published": false
}
}
EOF

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

client.associate("group", "<your group id>", "Securables", "< id of the public group>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagModify" , false,
    "flagUse" , true,
    "flagOwn" , false,
    "published" , true
  ) );

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagModify = false;
properties.flagUse = true;
properties.flagOwn = false;
properties.published = true;

client.associate("group", "<your group id>", "Securables", "< id of the public group>",     properties );

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

let promise = client.associate('group', '<your group id>', {
    role: 'Securables',
    id: '< id of the public group>'
}, {
    flagRead: true,
    flagModify: false,
    flagUse: true,
    flagOwn: false,
    published: true
} );

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

<?php
$client->associate('group', '<your group id>', 'Securables', '< id of the public group>', , 
  array (
    'flagRead' => true,
    'flagModify' => false,
    'flagUse' => true,
    'flagOwn' => false,
    'published' => true
  ) );
?>

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Securables",
  "id": "< id of the public group>"
},
  "properties": {
  "flagRead": true,
  "flagModify": false,
  "flagUse": true,
  "flagOwn": false,
  "published": true
}
}
EOF

Groups can be used to give a group of users access to securables (dashboards or datasets). In order to do so, the group has to be associated with the securables to give access. Several flags on the association you to control the type of access. An association without providing flags will not have effect.

Associate: Dataset

   Link a group to a securable, and give read/use/write access to that group 

client.associate("group", "<your group id>", "Securables", "< your securable (dashboard or dataset) id>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagModify" , true,
    "flagUse" , true,
    "flagOwn" , false
  ) );

   Link a group to a securable, and give read/use/write access to that group 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagModify = true;
properties.flagUse = true;
properties.flagOwn = false;

client.associate("group", "<your group id>", "Securables", "< your securable (dashboard or dataset) id>",     properties );

   Link a group to a securable, and give read/use/write access to that group 

let promise = client.associate('group', '<your group id>', {
    role: 'Securables',
    id: '< your securable (dashboard or dataset) id>'
}, {
    flagRead: true,
    flagModify: true,
    flagUse: true,
    flagOwn: false
} );

   Link a group to a securable, and give read/use/write access to that group 

<?php
$client->associate('group', '<your group id>', 'Securables', '< your securable (dashboard or dataset) id>', , 
  array (
    'flagRead' => true,
    'flagModify' => true,
    'flagUse' => true,
    'flagOwn' => false
  ) );
?>

   Link a group to a securable, and give read/use/write access to that group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Securables",
  "id": "< your securable (dashboard or dataset) id>"
},
  "properties": {
  "flagRead": true,
  "flagModify": true,
  "flagUse": true,
  "flagOwn": false
}
}
EOF

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

client.associate("group", "<id of the public group>", "Securables", "< your securable (dataset or dashboard) id>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagModify" , false,
    "flagUse" , false,
    "flagOwn" , false,
    "published" , false
  ) );

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagModify = false;
properties.flagUse = false;
properties.flagOwn = false;
properties.published = false;

client.associate("group", "<id of the public group>", "Securables", "< your securable (dataset or dashboard) id>",     properties );

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

let promise = client.associate('group', '<id of the public group>', {
    role: 'Securables',
    id: '< your securable (dataset or dashboard) id>'
}, {
    flagRead: true,
    flagModify: false,
    flagUse: false,
    flagOwn: false,
    published: false
} );

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

<?php
$client->associate('group', '<id of the public group>', 'Securables', '< your securable (dataset or dashboard) id>', , 
  array (
    'flagRead' => true,
    'flagModify' => false,
    'flagUse' => false,
    'flagOwn' => false,
    'published' => false
  ) );
?>

   Link the Public group to a securable, and give read access to everyone (necessary for private links) 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<id of the public group>",
  "resource": {
  "role": "Securables",
  "id": "< your securable (dataset or dashboard) id>"
},
  "properties": {
  "flagRead": true,
  "flagModify": false,
  "flagUse": false,
  "flagOwn": false,
  "published": false
}
}
EOF

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

client.associate("group", "<id of the public group>", "Securables", "< your securable (dataset or dashboard) id>", 
  ImmutableMap.of(
    "flagRead" , true,
    "flagModify" , false,
    "flagUse" , true,
    "flagOwn" , false,
    "published" , true
  ) );

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagModify = false;
properties.flagUse = true;
properties.flagOwn = false;
properties.published = true;

client.associate("group", "<id of the public group>", "Securables", "< your securable (dataset or dashboard) id>",     properties );

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

let promise = client.associate('group', '<id of the public group>', {
    role: 'Securables',
    id: '< your securable (dataset or dashboard) id>'
}, {
    flagRead: true,
    flagModify: false,
    flagUse: true,
    flagOwn: false,
    published: true
} );

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

<?php
$client->associate('group', '<id of the public group>', 'Securables', '< your securable (dataset or dashboard) id>', , 
  array (
    'flagRead' => true,
    'flagModify' => false,
    'flagUse' => true,
    'flagOwn' => false,
    'published' => true
  ) );
?>

   Link the Public group to a securable, and give read/use access to everyone and make sure it is listed in the public dashboards/datasets 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<id of the public group>",
  "resource": {
  "role": "Securables",
  "id": "< your securable (dataset or dashboard) id>"
},
  "properties": {
  "flagRead": true,
  "flagModify": false,
  "flagUse": true,
  "flagOwn": false,
  "published": true
}
}
EOF

Groups can be used to give a group of users access to securables (dashboards or datasets). In order to do so, the group has to be associated with the securables to give access. Several flags on the association you to control the type of access. An association without providing flags will not have effect.

Associate: User

   Link a user to a group and set him as member of that group 

client.associate("group", "<your group id>", "Users", "< your user id>", 
  ImmutableMap.of(
    "flagMember" , true,
    "flagOwn" , false
  ) );

   Link a user to a group and set him as member of that group 

dynamic properties = new ExpandoObject();
properties.flagMember = true;
properties.flagOwn = false;

client.associate("group", "<your group id>", "Users", "< your user id>",     properties );

   Link a user to a group and set him as member of that group 

let promise = client.associate('group', '<your group id>', {
    role: 'Users',
    id: '< your user id>'
}, {
    flagMember: true,
    flagOwn: false
} );

   Link a user to a group and set him as member of that group 

<?php
$client->associate('group', '<your group id>', 'Users', '< your user id>', , 
  array (
    'flagMember' => true,
    'flagOwn' => false
  ) );
?>

   Link a user to a group and set him as member of that group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Users",
  "id": "< your user id>"
},
  "properties": {
  "flagMember": true,
  "flagOwn": false
}
}
EOF

Groups can be used to give a group of users access to securables (dashboards or datasets). When associating a user with a group there are flags available that describe the kind of relation. Adding a user in a group without setting any flags will not have any effect. Only the owner of a group can add members to the group. The user who created the group automatically becomes an owner of the group.

Dissociate

   Example query that removes a user from a group 

client.dissociate("group", "<your group id>", "Users", "<user id>");

   Example query that removes a user from a group 

client.dissociate("group", "<your group id>", "Users", "<user id>");

   Example query that removes a user from a group 

let promise = client.dissociate('group', '<your group id>', {
    role: 'Users',
    id: '<user id>'
});

   Example query that removes a user from a group 

<?php
$client->associate('group', '<your group id>', "Users", "<user id>");
?>

   Example query that removes a user from a group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Users",
  "id": "<user id>"
}
}
EOF

   Example query removes access to a securable (dataset/dashboard) for a group 

client.dissociate("group", "<your group id>", "Securables", "<securable id>");

   Example query removes access to a securable (dataset/dashboard) for a group 

client.dissociate("group", "<your group id>", "Securables", "<securable id>");

   Example query removes access to a securable (dataset/dashboard) for a group 

let promise = client.dissociate('group', '<your group id>', {
    role: 'Securables',
    id: '<securable id>'
});

   Example query removes access to a securable (dataset/dashboard) for a group 

<?php
$client->associate('group', '<your group id>', "Securables", "<securable id>");
?>

   Example query removes access to a securable (dataset/dashboard) for a group 

curl https://api.cumul.io/0.1.0/group  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your group id>",
  "resource": {
  "role": "Securables",
  "id": "<securable id>"
}
}
EOF

Dissociating is similar for all resources. To break the link between two resources, simply provide the resource names and ids. Be careful that the 'role' of a resource is uppercase and usually plural. Dissociating can be done in both directions.

Organization

Each user belongs to precisely 1 organization (company or association). Billing plans and invoices are managed on the organization-level. Several things are restricted within an organization. For example a user can't list users from another organization and dashboards/datasets are by default not accessible to other users. However, in case it is necessary to share securables cross organization, securables can be associated directly to a user or group.

Properties

Actions

Note that create is not directly available, an organization is made when a new user without invite code is made.

Action: Create

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

JSONObject user = client.create("user",

  ImmutableMap.of(
    "email" , "example@cumul.io",
    "password" , "your-password",
    "name" , "Sam Examplius"
  ));
System.out.println("Success! %s%n", user);

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

dynamic properties = new ExpandoObject();
properties.email = "example@cumul.io";
properties.password = "your-password";
properties.name = "Sam Examplius";

dynamic user = client.create("user",    properties);
Console.WriteLine("Success!", user);

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

client.create('user',
  {
    email: 'example@cumul.io',
    password: 'your-password',
    name: 'Sam Examplius'
}

)
  .then(function(user) {
    console.log('Success!', user);
  });

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

<?php
$user = $client->create('user',

  array (
    'email' => 'example@cumul.io',
    'password' => 'your-password',
    'name' => 'Sam Examplius'
  )

);
print("Success! { $user }");
?>

   Example of the creation of a 'user' resource. If no invite code is provided this will also create a new organization 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "email": "example@cumul.io",
  "password": "your-password",
  "name": "Sam Examplius"
}
}
EOF

   After creating a user, you can retrieve the new organization that is linked to the user 

JSONObject data = client.get("user", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "id" , "<first user id>"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "Organization"
      )
    )
  ));

   After creating a user, you can retrieve the new organization that is linked to the user 

dynamic query = new ExpandoObject();
query.where = new {
      id = "<first user id>"
    };
query.include = new List<Object> {

      new {
        model = "Organization"
      }
    };

dynamic data = client.get("user",     query);

   After creating a user, you can retrieve the new organization that is linked to the user 

client.get('user', {
    where: {
        id: '<first user id>'
    },
    include: [
        {
            model: 'Organization'
        }
    ]
})
  .then(function(data) {
    console.log('Success!', data);
  });

   After creating a user, you can retrieve the new organization that is linked to the user 

<?php
$user = $client->get('user', 
  array (
    'where' => array (
      'id' => '<first user id>'
    ),
    'include' => array (

      array (
        'model' => 'Organization'
      )
    )
  ));

?>

   After creating a user, you can retrieve the new organization that is linked to the user 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "id": "<first user id>"
  },
  "include": [
    {
      "model": "Organization"
    }
  ]
}
}
EOF

An organization can not be made explicitly. The first user that you make determines your organization. Every new user that is created via the API either creates a new organization or is added to an existing organization via an inviteCode. If you need to bootstrap an organization programmatically this means you have to:

• Create the first user (which will create a trial)
• Retrieve the organization using the user id
• Update the organization details

This mechanism can be used to create organizations for your clients or bootstrap your organization completely from code.

Action: Update

   Update the name, adddress and payment method of an organization 

JSONObject organization = client.update("organization", "<your organization id>", 
  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "< organization name in English >",
      "fr" , "< organization name in French >"
    )
  ));

   Update the name, adddress and payment method of an organization 

dynamic properties = new ExpandoObject();
properties.name = new {
      en = "< organization name in English >",
      fr = "< organization name in French >"
    };

dynamic organization = client.update("organization", "<your organization id>", );

   Update the name, adddress and payment method of an organization 

client.update('organization',
  '<your organization id>',
  {
    name: {
        en: '< organization name in English >',
        fr: '< organization name in French >'
    }
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Update the name, adddress and payment method of an organization 

<?php
$user = $client->update('organization', '<your organization id>', 
  array (
    'name' => array (
      'en' => '< organization name in English >',
      'fr' => '< organization name in French >'
    )
  ));
?>

   Update the name, adddress and payment method of an organization 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "properties": {
  "name": {
    "en": "< organization name in English >",
    "fr": "< organization name in French >"
  }
}
}
EOF

Only the owner of the organization can update. The owner is the user that first created an account.

Action: Get

   Simple query to get users of an organization and order them 

JSONObject data = client.get("organization", 
  ImmutableMap.of(
    "attributes" , ImmutableList.of(
      "name"
    ),
    "where" , ImmutableMap.of(
      "id" , "< your organization id >"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "User"
      )
    ),
    "order" , ImmutableList.of(

      ImmutableList.of(

        ImmutableMap.of(
          "model" , "User"
        ),
        "name",
        "asc"
      )
    )
  ));

   Simple query to get users of an organization and order them 

dynamic query = new ExpandoObject();
query.attributes = new List<Object> {
      "name"
    };
query.where = new {
      id = "< your organization id >"
    };
query.include = new List<Object> {

      new {
        model = "User"
      }
    };
query.order = new List<Object> {

      new List<Object> {

        new {
          model = "User"
        },
        "name",
        "asc"
      }
    };

dynamic data = client.get("organization",     query);

   Simple query to get users of an organization and order them 

client.get('organization', {
    attributes: [
        'name'
    ],
    where: {
        id: '< your organization id >'
    },
    include: [
        {
            model: 'User'
        }
    ],
    order: [
        [
            {
                model: 'User'
            },
            'name',
            'asc'
        ]
    ]
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Simple query to get users of an organization and order them 

<?php
$user = $client->get('organization', 
  array (
    'attributes' => array (
      'name'
    ),
    'where' => array (
      'id' => '< your organization id >'
    ),
    'include' => array (

      array (
        'model' => 'User'
      )
    ),
    'order' => array (

      array (

        array (
          'model' => 'User'
        ),
        'name',
        'asc'
      )
    )
  ));

?>

   Simple query to get users of an organization and order them 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "attributes": [
    "name"
  ],
  "where": {
    "id": "< your organization id >"
  },
  "include": [
    {
      "model": "User"
    }
  ],
  "order": [
    [
      {
        "model": "User"
      },
      "name",
      "asc"
    ]
  ]
}
}
EOF

   Example of the return structure of a query of all levels when there is only one column with the 2 default hierarchylevels All & Values (Product type)

{
   "count": 1,
   "rows": [
     {
       "id": "5cce0379-0ee4-4bf3-bb18-4437aa40ce6b",
       "name": {
         "nl": "Jouw organisatie",
         "en": "Your organization",
         "fr": "Ton association"
       },
       "invitecode": "NlDcxH01pf",
       "address_line_1": null,
       "address_line_2": null,
       "zipcode": null,
       "city": null,
       "state": null,
       "vat": null,
       "legal_name": null,
       "payment_method": "creditcard",
       "country_id": null,
       "flag_allow_viewers": true,
       "created_at": "2018-08-31T10:03:34.203Z",
       "updated_at": "2018-08-31T10:03:34.203Z",
       "deleted_at": null,
       "locale_id": null,
       "theme_id": null,
       "flag_publish": false,
       "flag_whitelabeling": false,
       "main_color": null,
       "accent_color": null,
       "subdomain": null,
       "dpo_name": null,
       "dpo_address_line_1": null,
       "dpo_address_line_2": null,
       "dpo_email": null,
       "dpo_phone": null,
       "dpa_signed_by": null,
       "dpa_signed_on": null,
       "dpa_text": null,
       "from_email": null
     }
   ]
  }

Retrieve your organization. This can especially be useful to retrieve the invitecode of your organization to invite other users.

Action: Delete

   Delete a group using the id 

client.delete("organization", "<your organization id>");

   Delete a group using the id 

$client->delete("organization", "<your organization id>");

   Delete a group using the id 

let promise = client.delete('organization', '<your organization id>');

   Delete a group using the id 

<?php
$client->delete('organization', '<your organization id>');
?>

   Delete a group using the id 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>"
}
EOF

Delete an organization by providing the id of the organization.

Associations

Organizations their main connections are users and plugins. Besides of that you can also associate a default locale and a country to an organization and a thumbnail (logo of the organization) can be set.

Associate: User

   Your organization contains an invite code to add other users programmatically 

JSONObject data = client.get("organization", 
  ImmutableMap.of(

  ));
String invitecode = data.getJsonArray("rows").getJsonObject(0).getString("invitecode");

   Your organization contains an invite code to add other users programmatically 

dynamic query = new ExpandoObject();

dynamic data = client.get("organization",     query);
Console.WriteLine("Token Key is {0}", data["rows"][0]["invitecode"])

   Your organization contains an invite code to add other users programmatically 

client.get('organization', {})
  .then(function(data) {
    var invitecode = data.rows[0].invitecode;
  });

   Your organization contains an invite code to add other users programmatically 

<?php
$user = $client->get('organization', 
  array (

  ));
$invitecode = $data['rows'][0]['invitecode']
?>

   Your organization contains an invite code to add other users programmatically 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "find": {}
}
EOF
# result format of the organization contains the invite code
    { "count": 1,
      "rows":
       [ { "id": "7a7e327a-ea93-4275-a2cc-0f21b3701abc",
       "invitecode": "tZaG4MPeRX", 
       ....

   This invite code can then be used to add users to your organization 

JSONObject user = client.create("user",

  ImmutableMap.of(
    "name" , "New user of my organization",
    "email" , "user@organization.com",
    "password" , "... random password ...",
    "invitecode" , "CJ71ySxxxx"
  ));
System.out.println("Success! %s%n", user);

   This invite code can then be used to add users to your organization 

dynamic properties = new ExpandoObject();
properties.name = "New user of my organization";
properties.email = "user@organization.com";
properties.password = "... random password ...";
properties.invitecode = "CJ71ySxxxx";

dynamic user = client.create("user",    properties);
Console.WriteLine("Success!", user);

   This invite code can then be used to add users to your organization 

client.create('user',
  {
    name: 'New user of my organization',
    email: 'user@organization.com',
    password: '... random password ...',
    invitecode: 'CJ71ySxxxx'
}

)
  .then(function(user) {
    console.log('Success!', user);
  });

   This invite code can then be used to add users to your organization 

<?php
$user = $client->create('user',

  array (
    'name' => 'New user of my organization',
    'email' => 'user@organization.com',
    'password' => '... random password ...',
    'invitecode' => 'CJ71ySxxxx'
  )

);
print("Success! { $user }");
?>

   This invite code can then be used to add users to your organization 

curl https://api.cumul.io/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": "New user of my organization",
  "email": "user@organization.com",
  "password": "... random password ...",
  "invitecode": "CJ71ySxxxx"
}
}
EOF

The link between Organizations and Users is also a special case. You can't add users to an organization once the users are made. The only way to add users to an organization is on creation time by using an invite code. As shown in the code samples, the invitecode can be retrieved by getting your organization through the API.

If you use a correct invite code, the association between the organization and user will be made implicitely. Later on you can fetch the users of your organization using the 'include' syntax in a get call.

Associate: Plugin

   Link an organization to a plugin to make that plugin available to the organization 

client.associate("organization", "<your organization id>", "Plugins", "< your plugin id>");

   Link an organization to a plugin to make that plugin available to the organization 

client.associate("organization", "<your organization id>", "Plugins", "< your plugin id>");

   Link an organization to a plugin to make that plugin available to the organization 

let promise = client.associate('organization', '<your organization id>', {
    role: 'Plugins',
    id: '< your plugin id>'
});

   Link an organization to a plugin to make that plugin available to the organization 

<?php
$client->associate('organization', '<your organization id>', 'Plugins', '< your plugin id>', );
?>

   Link an organization to a plugin to make that plugin available to the organization 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "resource": {
  "role": "Plugins",
  "id": "< your plugin id>"
}
}
EOF

By default, when you make a plugin via the API, the plugin is only associated to the user that created it. By associating the plugin to the organization you make it available to all users in the organization. Associating a plugin to an organization can be done by each organization member.

Associate: Country

   Link an organization to a country 

client.associate("organization", "<your organization id>", "Countries", "FR");

   Link an organization to a country 

client.associate("organization", "<your organization id>", "Countries", "FR");

   Link an organization to a country 

let promise = client.associate('organization', '<your organization id>', {
    role: 'Countries',
    id: 'FR'
});

   Link an organization to a country 

<?php
$client->associate('organization', '<your organization id>', 'Countries', 'FR', );
?>

   Link an organization to a country 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "resource": {
  "role": "Countries",
  "id": "FR"
}
}
EOF

Associating an organization with a country simply gives us the information we need about your company. The association between country and organization serves as a default for the users of your organization which can be overridden by associating a country to a user directly.

Associate: Locale

   Link an organization to a locale to set a default locale for the users 

client.associate("organization", "<your organization id>", "Locales", "en");

   Link an organization to a locale to set a default locale for the users 

client.associate("organization", "<your organization id>", "Locales", "en");

   Link an organization to a locale to set a default locale for the users 

let promise = client.associate('organization', '<your organization id>', {
    role: 'Locales',
    id: 'en'
});

   Link an organization to a locale to set a default locale for the users 

<?php
$client->associate('organization', '<your organization id>', 'Locales', 'en', );
?>

   Link an organization to a locale to set a default locale for the users 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "resource": {
  "role": "Locales",
  "id": "en"
}
}
EOF

By associating a locale with your organization you set that locale as the default for the users in your organization. When a user has an association to a locale as well it will overrule the one from the organization. When you view a dashboard, the locale of the organization and/or user is taken into account to set the language.

Associate: Thumbnail

   Link an organization to a thumbnail to change the organizations Logo 

client.associate("organization", "<your organization id>", "Thumbnails", "< your thumbnail id >");

   Link an organization to a thumbnail to change the organizations Logo 

client.associate("organization", "<your organization id>", "Thumbnails", "< your thumbnail id >");

   Link an organization to a thumbnail to change the organizations Logo 

let promise = client.associate('organization', '<your organization id>', {
    role: 'Thumbnails',
    id: '< your thumbnail id >'
});

   Link an organization to a thumbnail to change the organizations Logo 

<?php
$client->associate('organization', '<your organization id>', 'Thumbnails', '< your thumbnail id >', );
?>

   Link an organization to a thumbnail to change the organizations Logo 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "associate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "resource": {
  "role": "Thumbnails",
  "id": "< your thumbnail id >"
}
}
EOF

It is possible to associate your organization to a thumbnail to change the Logo.

Dissociate

   Example that removes a user from an organization 

client.dissociate("organization", "<your organization id>", "Users", "<user id>");

   Example that removes a user from an organization 

client.dissociate("organization", "<your organization id>", "Users", "<user id>");

   Example that removes a user from an organization 

let promise = client.dissociate('organization', '<your organization id>', {
    role: 'Users',
    id: '<user id>'
});

   Example that removes a user from an organization 

<?php
$client->associate('organization', '<your organization id>', "Users", "<user id>");
?>

   Example that removes a user from an organization 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "resource": {
  "role": "Users",
  "id": "<user id>"
}
}
EOF

   Example that removes a plugin from an organization 

client.dissociate("organization", "<your organization id>", "Plugins", "<plugin id>");

   Example that removes a plugin from an organization 

client.dissociate("organization", "<your organization id>", "Plugins", "<plugin id>");

   Example that removes a plugin from an organization 

let promise = client.dissociate('organization', '<your organization id>', {
    role: 'Plugins',
    id: '<plugin id>'
});

   Example that removes a plugin from an organization 

<?php
$client->associate('organization', '<your organization id>', "Plugins", "<plugin id>");
?>

   Example that removes a plugin from an organization 

curl https://api.cumul.io/0.1.0/organization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "dissociate",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your organization id>",
  "resource": {
  "role": "Plugins",
  "id": "<plugin id>"
}
}
EOF

Dissociating is similar for all resources. To break the link between two resources, simply provide the resource names and ids. Be careful that the 'role' of a resource is uppercase and usually plural. Dissociating can be done in both directions.

Dataset

Contains the metadata associated with a single dataset.

The creating user is automatically given owner rights on the dataset. Any user can create new datasets. Only users with modify rights (either directly granted or via one or more groups) can update the dataset. This endpoint only creates datasets, to push data to the datasets you first have to add columns o the dataset with the column endpoint (Column) and then use the data endpoint to push data to the dataset.

Properties

Actions

Action: Create

   Creation of a dataset 

JSONObject securable = client.create("securable",

  ImmutableMap.of(
    "type" , "dataset",
    "name" , ImmutableMap.of(
      "en" , "<title of your dataset>"
    ),
    "subtitle" , ImmutableMap.of(
      "en" , "<subtitle of your dataset>"
    ),
    "description" , ImmutableMap.of(
      "en" , "<description of your dataset>"
    )
  ));
System.out.println("Success! %s%n", securable);

   Creation of a dataset 

dynamic properties = new ExpandoObject();
properties.type = "dataset";
properties.name = new {
      en = "<title of your dataset>"
    };
properties.subtitle = new {
      en = "<subtitle of your dataset>"
    };
properties.description = new {
      en = "<description of your dataset>"
    };

dynamic securable = client.create("securable",    properties);
Console.WriteLine("Success!", securable);

   Creation of a dataset 

client.create('securable',
  {
    type: 'dataset',
    name: {
        en: '<title of your dataset>'
    },
    subtitle: {
        en: '<subtitle of your dataset>'
    },
    description: {
        en: '<description of your dataset>'
    }
}

)
  .then(function(securable) {
    console.log('Success!', securable);
  });

   Creation of a dataset 

<?php
$securable = $client->create('securable',

  array (
    'type' => 'dataset',
    'name' => array (
      'en' => '<title of your dataset>'
    ),
    'subtitle' => array (
      'en' => '<subtitle of your dataset>'
    ),
    'description' => array (
      'en' => '<description of your dataset>'
    )
  )

);
print("Success! { $securable }");
?>

   Creation of a dataset 

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "dataset",
  "name": {
    "en": "<title of your dataset>"
  },
  "subtitle": {
    "en": "<subtitle of your dataset>"
  },
  "description": {
    "en": "<description of your dataset>"
  }
}
}
EOF

Any user with an API token can create a dataset. The user that creates the dataset will be automatically associated as the owner. Note that the creation of a dataset simply creates a securable of a certain type with properties such as name, title and description. To actually add data to the dataset you also have to create columns, associate them to the dataset and push data to the dataset.

Action: Update

   Update the name of a dataset 

JSONObject securable = client.update("securable", "<your securable id>", 
  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "<new title of your dataset>"
    )
  ));

   Update the name of a dataset 

dynamic properties = new ExpandoObject();
properties.name = new {
      en = "<new title of your dataset>"
    };

dynamic securable = client.update("securable", "<your securable id>", );

   Update the name of a dataset 

client.update('securable',
  '<your securable id>',
  {
    name: {
        en: '<new title of your dataset>'
    }
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Update the name of a dataset 

<?php
$user = $client->update('securable', '<your securable id>', 
  array (
    'name' => array (
      'en' => '<new title of your dataset>'
    )
  ));
?>

   Update the name of a dataset 

curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$CUMULIO_API_KEY",
  "token": "$CUMULIO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your securable id>",
  "properties": {
  "name": {
    "en": "<new title of your dataset>"
  }
}
}
EOF

Only the owner of the dataset can update the dataset. Other users can be made owner by associating them with the dataset and using the 'flagOwner'.

Action: Get

   Retrieve all datasets together with the users and groups that have access (only users and groups that you can access) 

JSONObject data = client.get("securable", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "type" , "dataset"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "Group",
        "include" , ImmutableList.of(

          ImmutableMap.of(
            "model" , "User"
          )
        )
      ),

      ImmutableMap.of(
        "model" , "User"
      )
    )
  ));

   Retrieve all datasets together with the users and groups that have access (only users and groups that you can access) 

dynamic query = new ExpandoObject();
query.where = new {
      type = "dataset"
    };
query.include = new List<Object> {

      new {
        model = "Group",
        include = new List<Object> {

          new {
            model = "User"
          }
        }
      },

      new {
        model = "User"
      }
    };

dynamic data = client.get("securable",     query);

   Retrieve all datasets together with the users and groups that have access (only users and groups that you can access) 

client.get('securable', {
    where: {
        type: 'dataset'
    },
    include: [
        {
            model: 'Group'