curl Node.js PHP Java .NET
  • Introduction
  • Guides
  • Core API
  • Integration API
  • Plugin API
  • 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:

    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 support@cumul.io.

    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "username": "< A unique identifier for your end user >",
        "name": "< end-user name >",
        "email": "< end-user email >"
      }
    }
    EOF
    
       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 
    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: '24 hours',
      inactivity_interval: '10 minutes',
      username: '< A unique identifier for your end user >',
      name: '< end-user name >',
      email: '< end-user email >'
    });
    
    promise.then(function(result){
      // return the result to the client
    })
    
    
       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 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize('< your API key >', '< your API token >');
    
    $authorization = $client->create('authorization', array(
      'type' => 'temporary',
      'expiry' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'username' => '< A unique identifier for your end user >',
      'name' => '< end-user name >',
      'email' => '< end-user email >'
    ));
    ?>
    
       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 
    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 authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
        .put("securables", ImmutableList.of(
            "< dashboard id >", 
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .put("name", "< end-user name >")
      .put("email", "< end-user email >")
      .build()
    );
    
       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 
    Cumulio client = new Cumulio("< Your API key >", "< Your API token >");
    
    dynamic properties = new ExpandoObject();
    properties.type = "temporary";
    properties.expiry = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.username = "< A unique identifier for your end user >";
    properties.name = "< end-user name >";
    properties.email = "< end-user email >";
    
    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.
    username
    string
    (optional but recommended) The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.
    name
    string
    (optional) The name of the end-user.
    email
    string
    (optional) The email address of the end-user.

    You can also set an initialization filter that you want to apply to a certain filter object 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

    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "username": "< A unique identifier for your end user >",
        "name": "< end-user name >",
        "email": "< end-user email >",
        metadata: { 
          "< Parameter name > " : ["< value to apply >", "< other value to apply >"]
          }
      }
    }
    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: '24 hours',
      inactivity_interval: '10 minutes',
      username: '< A unique identifier for your end user >',
      name: '< end-user name >',
      email: '< end-user email >',
      metadata: { 
        Parameter_name: ['< value to apply >', '< other value to apply >']
       }
    });
    
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize('< your API key >', '< your API token >');
    
    $authorization = $client->create('authorization', array(
      'type' => 'temporary',
      'expiry' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'username' => '< A unique identifier for your end user >',
      'name' => '< end-user name >',
      'email' => '< end-user email >',
      'metadata' => array( 
        '< Parameter name >' => array(
          '< value to apply >',
          '< other value to apply >'
       )
    ));
    ?>
    
    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 authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >",
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .put("name", "< end-user name >")
      .put("email", "< end-user email >")
      .put("metadata", ImmutableMap.builder()
        .put("< Parameter name >", ImmutableList.of(
          "< value to apply >",
          "< other value to apply >"
        ))
        .build()
      )
      .build()
    );
    
    Cumulio client = new Cumulio("< Your API key >", "< Your API token >");
    
    dynamic properties = new ExpandoObject();
    properties.type = "temporary";
    properties.expiry = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.username = "< A unique identifier for your end user >";
    properties.name = "< end-user name >";
    properties.email = "< end-user email >";
    properties.metadata = new {
      parameter_name = new List<String> {
        "< value to apply >",
        "< other value to apply >"
      }
    }
    
    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.
    username
    string
    (optional but recommended) The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.
    name
    string
    (optional) The name of the end-user.
    email
    string
    (optional) The email address of the end-user.
    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "username": "< A unique identifier for your end user >",
        "name": "< end-user name >",
        "email": "< end-user email >",
        "account_overrides": { 
          "< Your account_id >" : {
            "host": "< The new database host to connect to. >"
          }
        }
      }
    }
    EOF
    
       Override the host property of your standard connector (database) account 
    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: '24 hours',
      inactivity_interval: '10 minutes',
      username: '< A unique identifier for your end user >',
      name: '< end-user name >',
      email: '< end-user email >',
      account_overrides: { 
        '< your account_id >': {
          host: '< The new database host to connect to. >'
        }
       }
    });
    
       Override the host property of your standard connector (database) account 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize('< your API key >', '< your API token >');
    
    $authorization = $client->create('authorization', array(
      'type' => 'temporary',
      'expiry' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'username' => '< A unique identifier for your end user >',
      'name' => '< end-user name >',
      'email' => '< end-user email >',
      'account_overrides' => array( 
        '< your account_id >' => array(
          'host' => '< The new database host to connect to. >'
        )
       )
    ));
    ?>
    
       Override the host property of your standard connector (database) account 
    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 authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >",
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .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()
    );
    
       Override the host property of your standard connector (database) account 
    Cumulio client = new Cumulio("< Your API key >", "< Your API token >");
    
    dynamic properties = new ExpandoObject();
    properties.type = "temporary";
    properties.expiry = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.username = "< A unique identifier for your end user >";
    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);
    
         Temporary token An example showing how to apply dataset level overrides when using account_overrides.
    
    private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >",
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .put("name", "< end-user name >")
      .put("email", "< end-user email >")
      .put("account_overrides", ImmutableMap.builder()
        .put("< your account_id >", ImmutableMap.builder()
          .put("datasets", ImmutableMap.builder()
            .put("< dataset ID >", ImmutableMap.builder()
              .put("table", "< new table name >")
              .build()
            )
            .build()
          )
          .build()
        )
        .build()
      )
      .build()
    );
    System.out.println("Success! %s%n", authorization);
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.  
    
    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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.username = "< A unique identifier for your end user >";
    properties.name = "< end-user name >";
    properties.email = "< end-user email >";
    properties.account_overrides = new {
      < account ID > = new {
        datasets = new {
          < dataset ID > = new {
            table = "< my new table name >"
          }
        }
      }
    };
    
    dynamic authorization = client.create("authorization",    properties);
    Console.WriteLine("Success!", authorization);
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.  
    
    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: '24 hours',
        inactivity_interval: '10 minutes',
        username: '< A unique identifier for your end user >',
        name: '< end-user name >',
        email: '< end-user email >',
        account_overrides: {
          '< account ID >': {
            datasets: {
              '< dataset ID >': {
                table: '< my new table name >'
              }
            }
          }
        }
      }
    
    )
      .then(function(authorization) {
        console.log('Success!', authorization);
      });
    
         Temporary token An example showing how to apply dataset level overrides when using account_overrides.
    
    <?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' => '24 hours',
        'inactivity_interval' => '10 minutes',
        'username' => '< A unique identifier for your end user >',
        'name' => '< end-user name >',
        'email' => '< end-user email >',
        'account_overrides' => array (
          '< account ID >' => array (
            'datasets' => array (
              '< dataset ID >' => array (
                'table' => '< my new table name >'
              )
            )
          )
        )
      )
    
    );
    print("Success! { $authorization }");
    ?>
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.
    
    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "username": "< A unique identifier for your end user >",
        "name": "< end-user name >",
        "email": "< end-user email >",
        "account_overrides": {
          "< account ID >": {
            "datasets": {
              "< dataset ID >": {
                "table": "< my new table name >"
              }
            }
          }
        }
      }
    }
    EOF
    
    

    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.
    username
    string
    (optional but recommended) The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.
    name
    string
    (optional) The name of the end-user.
    email
    string
    (optional) The email address of the end-user.
    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.
    database
    string
    The new database to retrieve data from.
    Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value for both schema and database
    schema
    string
    The new schema to retrieve data from.
    Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value for both schema and database
    table
    string
    The new table to retrieve data from.
    datasets
    object
    List of dataset-level overrides. Useful if you want to override only a single table in your dashboard or if you have a separate table per client. The SQL query of the dataset can also be overridden if it's a SQL dataset within Cumul.io. Allowing you to call stored procedures for example.
    dataset_id
    string
    The dataset (securable) ID that you want to override.
    table
    string
    The new table to retrieve data from.
    schema
    string
    The new schema to retrieve data from.
    sql
    string
    The new SQL query to run. NOTE: the columns returned in the new query need to conform to the same schema as the original dataset.
    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": "24 hours",
        "inactivity_interval": "10 minutes",
        // Optional 'user context'
        "username": "< A unique identifier for your end user >",
        "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: '24 hours',
      inactivity_interval: '10 minutes',
      // Optional 'user context'
      username: '< A unique identifier for your end user >',
      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' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'username' => '< A unique identifier for your end user >',
      '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 JSONObject authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >",
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.username = "< A unique identifier for your end user >";
    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 properties 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 but recommended) The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.
    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 property.

    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 of the filter object, 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": "24 hours",
        "inactivity_interval": "10 minutes",
        "username": "< A unique identifier for your end user >",
        "name": "< end-user name >",
        "email": "< end-user email >",
        "filters": [
          {
            "clause": "where",
            "origin": "initialization",
            "chart_id": "< chart id of a filter object contained in the dashboard >",
            "expression": "? = ?",
            "value": "< value to be applied to the expression >"
          }
        ]
      }
    }
    EOF
    
       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 of the filter object, the expression to be used and the filter value of your choice. 
    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: '24 hours',
      inacivity_interval: '10 minutes',
      username: '< A unique identifier for your end user >',
      name: '< end-user name >',
      email: '< end-user email >',
      filters: [
        {
          clause: 'where',
          origin: 'initialization',
          chart_id: '< chart id of a filter object contained in the dashboard >',
          expression: '? = ?',
          value: '< value to be applied to the expression >'
        }
      ]
    });
    
    promise.then(function(result){
      // return the result to the client
    })
    
       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 of the filter object, the expression to be used and the filter value of your choice. 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize('< your API key >', '< your API token >');
    
    $authorization = $client->create('authorization', array(
      'type' => 'temporary',
      'expiry' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'username' => '< A unique identifier for your end user >',
      'name' => '< end-user name >',
      'email' => '< end-user email >',
      'filters' => array(
        array(
          'clause'     => 'where',
          'origin'     => 'initialization',
          'chart_id'   => '< chart id of a filter object contained in the dashboard >',
          'expression' => '? = ?',
          'value'      => '< value to be applied to the expression >'
        )
      ),                      
    ));
    ?>
    
       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 of the filter object, the expression to be used and the filter value of your choice. 
    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 authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >", 
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .put("name", "< end-user name >")
      .put("email", "< end-user email >")
      .put("filters", ImmutableList.of(
        ImmutableMap.builder()
        .put("clause",       "where")
        .put("origin",       "initialization")
        .put("chart_id",     "< chart id of a filter object contained in the dashboard >")
        .put("expression",   "? = ?")
        .put("value",        "< value to be applied to the expression >")
        .build()
      ))
      .build()
    );
    
       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 of the filter object, the expression to be used and the filter value of your choice. 
    Cumulio client = new Cumulio("< Your API key >", "< Your API token >");
    
    dynamic properties = new ExpandoObject();
    properties.type = "temporary";
    properties.expiry = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.username = "< A unique identifier for your end user >";
    properties.name = "< end-user name >";
    properties.email = "< end-user email >";
    properties.filters = new List<dynamic> {
      new {
        clause = "where",
        origin = "initialization",
        chart_id = "< chart id of a filter object contained in the dashboard >",
        expression = "? = ?",
        value = "< value to be applied to the expression >"
      }
    };
    
    dynamic authorization = client.create("authorization", properties);
    Console.WriteLine("Success!", authorization);
    
       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 id of the chart object, the dataset id and column id used in that chart, the expression to be used and the filter value of your choice. 
    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 authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >", 
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("username", "< A unique identifier for your end user >")
      .put("name", "< end-user name >")
      .put("email", "< end-user email >")
      .put("filters", ImmutableList.of(
        ImmutableMap.builder()
        .put("clause",       "where")
        .put("origin",       "initialization")
        .put("chart_id",     "< chart id of a chart object contained in the dashboard >")
        .put("expression",   "? = ?")
        .put("column_id",    "< id of the column you want to filter on (usually in category slot) >")
        .put("securable_id", "< id of the dataset that the column belongs to >")
        .put("value",        ImmutableList.of(
          "<value to be applied to the expression>"
        ))
        .build()
      ))
      .build()
    );
    
       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 id of the chart object, the dataset id and column id used in that chart, the expression to be used and the filter value of your choice. 
    Cumulio client = new Cumulio("< Your API key >", "< Your API token >");
    
    dynamic properties = new ExpandoObject();
    properties.type = "temporary";
    properties.expiry = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.username = "< A unique identifier for your end user >";
    properties.name = "< end-user name >";
    properties.email = "< end-user email >";
    properties.filters = new List<dynamic> {
      new {
        clause = "where",
        origin = "initialization",
        chart_id = "< chart id of a chart object contained in the dashboard >",
        expression = "? = ?",
        column_id = "< id of the column to apply the filter to (usually the category) >",
        securable_id = "< id of the dataset that the column belongs to >",
        value = new List<string> {
          "< value to be applied to the expression >"
        }
      }
    };
    
       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 id of the chart object, the dataset id and column id used in that chart, the expression to be used and the filter value of your choice. 
    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: '24 hours',
      inactivity_interval: '10 minutes',
      username: '< A unique identifier for your end user >',
      name: '< end-user name >',
      email: '< end-user email >',
      filters: [
        {
          clause: 'where',
          origin: 'initialization',
          chart_id: '< chart id of a chart object contained in the dashboard >',
          expression: '? = ?',
          column_id: '< id of the column to apply the filter to (usually the category) >',
          securable_id: '< id of the dataset that the column belongs to >',
          value: [
            '< value to be applied to the expression >'
          ]
        }
      ]
    });
    
    promise.then(function(result){
      // return the result to the client
    })
    
       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 id of the chart object, the dataset id and column id used in that chart, the expression to be used and the filter value of your choice. 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize('< your API key >', '< your API token >');
    
    $authorization = $client->create('authorization', array(
      'type' => 'temporary',
      'expiry' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'username' => '< A unique identifier for your end user >',
      'name' => '< end-user name >',
      'email' => '< end-user email >',
      'filters' => array(
        array(
          'clause'       => 'where',
          'origin'       => 'initialization',
          'chart_id'     => '< chart id of a chart object contained in the dashboard >',
          'expression'   => '? = ?',
          'column_id'    => '< id of the column to apply the filter to (usually the category) >',
          'securable_id' => '< id of the dataset that the column belongs to >'
          'value'        => array(
            '< value to be applied to the expression >'
          )
        )
      ),                      
    ));
    ?>
    
       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 id of the chart object, the dataset id and column id used in that chart, 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": "24 hours",
        "inactivity_interval": "10 minutes",
        "username": "< A unique identifier for your end user >",
        "name": "< end-user name >",
        "email": "< end-user email >",
        "filters": [
          {
            "clause": "where",
            "origin": "initialization",
            "chart_id": "< chart id of a chart object contained in the dashboard >",
            "expression": "? = ?",
            "column_id": "< id of the column to apply the filters to >",
            "securable_id": "< id of the dataset that the column belongs to >",
            "value": [
              "< value to be applied to the expression >"
            ]
          }
        ]
      }
    }
    EOF
    

    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 on a filter object, 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.

    You can also set initialization filters on chart objects. This pre-selects a portion of the chart when the dashboard opens. The structure in this case is slightly different: you need a column_id and a securable_id. You also need to make sure that the values you are passing are contained in an array.

    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 but recommended) The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.
    name
    string
    (optional) The name of the end-user.
    email
    string
    (optional) The email address of the end-user.
    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.
    column_id
    string
    (Only needed in case of a non-filter object) The column to apply the filter to
    securable_id
    string
    (Only needed in case of a non-filter object) The dataset to apply the filter to

    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.

    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

       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
    

    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

       In curl, there is no need for an initial authentication. Use your API key & token in every API call. 
       Replace with your API key and token. 
    const Cumulio = require('cumulio');
    var client = new Cumulio({
      api_key: '< your API key >',
      api_token: '< your API token >'
    });
    
       Replace with your API key and token. 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize(
      '< your API key >',
      '< your API token >'
    );
    ?>
    
       Replace with your API key and token. 
    private Cumulio client = new Cumulio("< Your API key >","< Your API token >");
    
       Replace with your API key and 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.

    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 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
    
       Replace with your API key & token and a valid dataset id. 
    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();
      });
    
       Replace with your API key & token and a valid dataset id. 
    <?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);
    ?>
    
       Replace with your API key & token and a valid 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 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));
    
       Replace with your API key & token and a valid dataset id. 
    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 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
    
       Replace with your API key & token. 
    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();
      });
    
       Replace with your API key & token. 
    <?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);
    ?>
    
       Replace with your API key & token. 
    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));
    
       Replace with your API key & token. 
    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! ".json_encode($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
    
       This code snippet creates a new dataset: 
    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);
     });
    
       This code snippet creates a new dataset: 
    <?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 >'
      )
    ));
    ?>
    
       This code snippet creates a new dataset: 
    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 >"
      )
    ));
    
       This code snippet creates a new dataset: 
    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
    
       This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset: 
    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(...);
    
       This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset: 
    <?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 >'
        )
      )
    );
    ?>
    
       This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset: 
    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 >"
        )
      )
    )
    );
    
       This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset: 
    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
    
       This code snippet associates the specified column with a specified dataset. 
    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 >'
    });
    
       This code snippet associates the specified column with a specified dataset. 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize(
      '< your API key >',
      '< your API token >'
    );
    
    $securable = $client->associate(
      'securable',
      '< your dataset id >',
      'Columns',
      '< your column id >');
    ?>
    
       This code snippet associates the specified column with a specified dataset. 
    private Cumulio client = new Cumulio("< Your API key >","< Your API token >");
    
    client.associate("column", "< your column id >", "securable", "< your dataset id >");
    
       This code snippet associates the specified column with a specified dataset. 
    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! ".json_encode($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! ".json_encode($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! ".json_encode($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 the 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
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    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]]
      });
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    <?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]]
    ?>
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    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]]
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    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",
            "bins": "10"
          }
        }],
        "measures": [{
          "column_id": "Number burritos savoured column id",
          "dataset_id": "< your dataset id >",
          "aggregation": {
            "type": "sum"
          }
        }],
        "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 >",
          "aggregation": {
            "type": "sum"
          },
          "order": "desc"
        }],
        "limit": {
          "by": "5"
        }
      }
    }
    EOF
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    client.query({
     dimensions: [{
       column_id: 'Burrito weight column id',
       dataset_id: '< your dataset id >',
       discretization: {
         type: 'linear',
         bins: 10
       }
     }],
     measures: [{
       column_id: 'Number burritos savoured column id',
       dataset_id: '< your dataset id >',
       aggregation: {
         type: 'sum'
       }
     }],
     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 >',
       aggregation: {
         type: 'sum'
       }
       order: 'desc'
     }],
     limit: {
       by: 5
     }
    })
     .then(function(data) {
       console.log('Result set:', data.data);
       // Prints: [['[ 100 - 150 [', 125],
       //            ['[ 150 - 200 [', 121]]
     });
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    <?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',
              'bins' => 10
            )
          )
        ),
        'measures' => array(
          array(
            'column_id' => 'Number burritos savoured column id',
            'dataset_id' => '< your dataset id >',
            'aggregation' => array(
              'type' => 'sum'
            )
          )
        ),
        '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',
            'aggregation' => array(
              'type' => 'sum'
            )
          )
        ),
        'limit' => array(
          'by' => 5
        )
      )
    );
    
    print_r($data);
    // Prints: [['[ 100 - 150 [', 125],
    //            ['[ 150 - 200 [', 121]]
    ?>
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    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",
              "bins", 10
            )
          )
        ),
        "measures", ImmutableList.of(
          ImmutableMap.of(
            "column_id", "Number of burritos savoured column id",
            "dataset_id", "< your dataset id >",
            "aggregation" = new {
              "type"= "sum"
            }
          )
        ),
        "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 >",
            "aggregation" = new {
              "type"= "sum"
            },
            "order", "desc"
          )
        ),
        "limit", ImmutableMap.of(
          "by", 5
        )
      )
    );
    
    System.out.println(data.toString(2));
    // Prints: [['[ 100 - 150 [', 125],
    //          ['[ 150 - 200 [', 121]]
    
       Replace with your own API key & token, a valid dataset id and valid column id's. 
    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",
          bins = 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. These bins will be made by equally dividing the range between the minimum and maximum values in the column specified.

    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
    
       This code snippet notifies Cumul.io that a dataset has changed via an external source: 
    const Cumulio = require('./cumulio');
    var client = new Cumulio({
      api_key: '< your API key >',
      api_token: '< your API token >'
    });
    
    client.update('data', '< your dataset id >');
    
       This code snippet notifies Cumul.io that a dataset has changed via an external source: 
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize(
      '< your API key >',
      '< your API token >'
    );
    
    $client->update('data', '< your dataset id >', array());
    ?>
    
       This code snippet notifies Cumul.io that a dataset has changed via an external source: 
    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()));
    
       This code snippet notifies Cumul.io that a dataset has changed via an external source: 
    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:

    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.

    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: %3 <!-- Dashboard --> Dashboard Dashboard <!-- Securable --> Securable Securable <!-- Dashboard->Securable --> Dashboard->Securable <!-- Dataset --> Dataset Dataset <!-- Dataset->Securable --> Dataset->Securable <!-- Account --> Account Account <!-- User --> User User <!-- User->Account --> User->Account <!-- Authorization --> Authorization Authorization <!-- User->Authorization --> User->Authorization <!-- Locale --> Locale Locale <!-- User->Locale --> User->Locale <!-- User->Securable --> User->Securable <!-- Country --> Country Country <!-- User->Country --> User->Country <!-- Organization --> Organization Organization <!-- User->Organization --> User->Organization <!-- Thumbnail --> Thumbnail Thumbnail <!-- User->Thumbnail --> User->Thumbnail <!-- Share --> Share Share <!-- User->Share --> User->Share <!-- Group --> Group Group <!-- User->Group --> User->Group <!-- Schedule --> Schedule Schedule <!-- User->Schedule --> User->Schedule <!-- Plugin --> Plugin Plugin <!-- User->Plugin --> User->Plugin <!-- Locale->Authorization --> Locale->Authorization <!-- Theme --> Theme Theme <!-- Theme->Authorization --> Theme->Authorization <!-- Theme->Organization --> Theme->Organization <!-- Column --> Column Column <!-- Column->Column --> Column->Column <!-- Securable->Column --> Securable->Column <!-- Securable->Securable --> Securable->Securable <!-- HierarchyLevel --> HierarchyLevel HierarchyLevel <!-- HierarchyLevel->Column --> HierarchyLevel->Column <!-- Organization->Locale --> Organization->Locale <!-- Organization->Country --> Organization->Country <!-- Thumbnail->Securable --> Thumbnail->Securable <!-- Thumbnail->Organization --> Thumbnail->Organization <!-- Thumbnail->Plugin --> Thumbnail->Plugin <!-- Tag --> Tag Tag <!-- Tag->Securable --> Tag->Securable <!-- Share->Locale --> Share->Locale <!-- Share->Securable --> Share->Securable <!-- Group->Securable --> Group->Securable <!-- Schedule->Securable --> Schedule->Securable <!-- Plugin->Securable --> Plugin->Securable <!-- Plugin->Organization --> Plugin->Organization

    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:

    Create
    Get
    List
    Update
    Delete
    Associate
    Dissociate

    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, …

    Parameter
    Description
    resource:
    string
    The lowercase name of the resource we want to create
    properties:
    object
    Here you provide the properties of the entity you want to create in the form of a map/object

    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.

    Parameter
    Description

    Resource
    string
    The lowercase name of the resource we want to update

    Id
    uuid
    The id of the entity to update

    Properties
    object
    Here you provide the properties of the entity you want to update in the form of a map/object. If a property is not present in the map, it will remain untouched

    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
    

    Delete a resource, eg. delete a dataset or group.

    Parameter
    Description

    Resource
    string
    The lowercase name of the resource we want to delete

    Id
    uuid
    The id of the entity to delete

    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 action if you fetch an entity using a specific id in the where clause, else it is considered to be a list action. The query syntax is very close to SQL, it consists of the following attributes:

    Parameter
    Description
    resource:
    string
    The lowercase name of the resource we want to get or list
    query:
    object
    A query object consisting of SQL-like keywords such as: where, include, attributes, order
    attributes:
    string[]
    instead of returning all attributes, limit the set of attributes to the given list
    where:
    object[]
    Filter the selection, each where statement has to match
    include:
    object[]
    embed a connected object in the results, within an include you can again use where, include, attributes
    order:
    array[]
    Order on attributes. Either provide only an attribute and 'desc' or 'asc' to filter on a top-level attribute. or provide models in the beginning of the array if you want to target the attribute of an embedded resource.

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

    Parameter
    Description

    id:
    uuid
    The uuid of the resource you want to associate with another resource

    resource:
    object
    An object indicating which resource type (role) and which entity (id)

    role:
    string
    the role of the to-be-associated resource which is usually the capitalized plural name of the resource e.g. 'Users', 'Organizations'

    id:
    uuid
    the id of the to-be-associated resource

    properties:
    object
    some associations can have property set on them. e.g. on a User - Dataset relationship, there is a flagOwner property

    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 disassociated please refer to the schema at the beginning of this chapter Schema).

    Parameter
    Description

    id:
    uuid
    The uuid of the resource you want to dissociate with another resource

    resource:
    object
    An object indicating which resource type (role) and which entity (id)

    role:
    string
    the role of the to-be-dissociated resource which is usually the capitalized plural name of the resource e.g. 'Users', 'Organizations'

    id:
    uuid
    the id of the to-be-dissociated resource

    Resources

    Account

    Accounts contain the information necessary to access a certain plugin (e.g. Teamleader, Google Drive, your own custom plugin, etc..) or database The easiest to understand what a plugin is to show you what part of the UI makes an account (see the screenshot below). When you add a database connection and click 'connect' an account is created to make sure you can connect when you retrieve datasets later on.

    Note that accounts employ a general terminology to accommodate both different plugins as dataproviders. Eg. a token in Cumul.io terminology corresponds to a 'password' in a DB, where a scope in Cumul.io terminology refers to the 'database' in a db which can have a different meaning in a plugin.

    Properties

    Parameter
    Description

    id
    uuid
    Unique key of the account (automatically assigned)

    provider
    string
    Type of data provider to retrieve data from. Either the 'slug' of a plugin, e.g. googleanalytics, googledrive, quandl, salesforce, mailchimp, etc... the slug of your own plugin or one of a database such as 'postgresql'. Slugs are unique short names for plugins and dataproviders (such as dbs)

    date
    datetime
    Date/time this account was linked by the user. Defaults to the current date.

    expiry
    datetime
    Expiry date of the credentials.

    scope
    string
    Provider-specific description of services used (eg. which accesses were granted, which database is used, ...).

    host
    string
    Endpoint of this account. For relational database connections, this corresponds to the hostname of the database.

    active
    boolean
    Indicates whether queries may be sent to this database or plugin connection. You can use this field to eg. temporarily disable any connections / queries. This might be useful in case of elevated stress on your systems.

    invalid
    boolean
    Read-only. Indicates whether this connection has been disabled because the source system reported that the used credentials are invalid.

    token
    boolean
    Token or password of this account.

    identifier
    string
    Key or username of this account.

    cache
    integer
    Defaults to 0. Number of seconds queries to this data connector are cached in Cumul.io's caching layer. Use 0 to disable caching for this connector entirely. Note that queries might still not be cached if there are other uncached data connectors called in a query. You can invalidate the cache before the expiry time by calling the update method on the data endpoint.

    code
    string
    (Update-only) OAauth2 authorization code used to retrieve an access token and refresh token.

    Actions

    Create
    Update
    Get
    List
    Delete

    Action: Create

       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("Account id: %s%n", account.get("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("Account id is {0}", account["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 account_id = account.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['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 account id 
    {
     ... 
     "id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
    ...
    }
    
    Create
    can be executed by:
    Logged-in User

    Action: Update

       Update the credentials of an account 
    JSONObject account = client.update("account", "<your account id>", 
      ImmutableMap.of(
        "identifier" , "<username>",
        "token" , "<password>"
      ));
    
       Update the credentials of an account 
    dynamic properties = new ExpandoObject();
    properties.identifier = "<username>";
    properties.token = "<password>";
    
    dynamic account = client.update("account", "<your account id>", );
    
       Update the credentials of an account 
    client.update('account',
      '<your account id>',
      {
        identifier: '<username>',
        token: '<password>'
    }
    )
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Update the credentials of an account 
    <?php
    $user = $client->update('account', '<your account id>', 
      array (
        'identifier' => '<username>',
        'token' => '<password>'
      ));
    ?>
    
       Update the credentials of an account 
    curl https://api.cumul.io/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "update",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your account id>",
      "properties": {
      "identifier": "<username>",
      "token": "<password>"
    }
    }
    EOF
    
    Update
    can be executed by:
    Account Owner

    Action: Get

       Retrieve all your accounts 
    JSONObject data = client.get("account", 
      ImmutableMap.of(
    
      ));
    
    
       Retrieve all your accounts 
    dynamic query = new ExpandoObject();
    
    dynamic data = client.get("account",     query);
    
    
       Retrieve all your accounts 
    client.get('account', {})
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Retrieve all your accounts 
    <?php
    $user = $client->get('account', 
      array (
    
      ));
    
    ?>
    
       Retrieve all your accounts 
    curl https://api.cumul.io/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "get",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "find": {}
    }
    EOF
    
    
    Get
    can be executed by:
    Account Reader
    List
    can be executed by:
    Account Reader

    Retrieving accounts.

    Action: Delete

       Delete an account 
    client.delete("account", "<your account id>");
    
       Delete an account 
    $client->delete("account", "<your account id>");
    
       Delete an account 
    let promise = client.delete('account', '<your account id>');
    
       Delete an account 
    <?php
    $client->delete('account', '<your account id>');
    ?>
    
       Delete an account 
    curl https://api.cumul.io/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "delete",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your account id>"
    }
    EOF
    
    Delete
    can be executed by:
    Account Owner

    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

    As can be seen from the schema, accounts are only linked to users. This link to accounts is created automatically so you will never associate an account manually.

    %3 <!-- Account --> Account Account <!-- User --> User User <!-- User->Account --> User->Account

    Associate: User (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",
    ...
    }
    
    User
    Account
    Associate
    requires:
    Account Owner
    and
    User Owner

    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.

    Alert

    Alerts allow a user to be notified when some interesting condition on their data is met. A simple example is an email send to the sales team when the quarterly sales target has been exceeded.

    The core elements of an alert are the query that checks the condition and the communication channels through which a notification will be send.

    The query can be any valid query that could be send to the data service. When the query returns at least one row, the condition is assumed to have been met and the alert is fired.

    A single alert can have multiple configured channels. Each will receive a message when the alert fires. Currently only email is supported as a channel, but more will follow.

    Properties

    Parameter
    Description
    id
    uuid
    Unique key of the alert (automatically assigned)
    name
    localized
    Title of the alert
    query
    json
    The query to execute
    frequency
    json
    Defines the frequency at which the condition is checked. Consists of a json object containing 2 properties: 'unit'(minute, hour, day, week, month, quarter, year) and 'quantity'
    channels
    json
    Array of channel configurations

    Actions

    Create
    Update
    Get
    List
    Delete

    Action: Create

       Alerts are linked to users on creation 
    JSONObject account = client.create("alert",
    
      ImmutableMap.of(
        "name" , ImmutableMap.of(
          "en" , "<title of your alert>"
        ),
        "query", ImmutableMap.of(
          "dimensions" , ImmutableList.of(
    
            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Type of burrito column id >"
            )
          ),
          "measures" , ImmutableList.of(
    
            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Number of burritos column id >",
              "aggregation" , ImmutableMap.of(
                "type" , "sum"
              )
            )
          ),
          "where" , ImmutableList.of(
    
            ImmutableMap.of(
              "expression" , "? in ?",
              "parameters" , ImmutableList.of(
    
                ImmutableMap.of(
                  "dataset_id" , "< Burrito dataset id >",
                  "column_id" , "< Type of burrito column id >"
                ),
                ImmutableList.of("Quesarito", "Chicken baconito")
              )
            )
          ),
          "having", ImmutableList.of(
    
            ImmutableMap.of(
              "expression" , "? >= ?",
              "parameters" , ImmutableList.of(
                ImmutableMap.of(
                  "dataset_id" , "< Burrito dataset id >",
                  "column_id" , "< Sold units column id >"
                  aggregation: {
                    type: 'sum'
                  }
                ),
                10000
              )
            )
          )
        ),
        "frequency", ImmutableMap.of(
          "unit", "day",
          "quantity", 1 
        ),
        "channels, ImmutableList.of(
          ImmutableMap.of(
            "type", "email",
            "config", ImmutableMap.of(
              "recipients", ImmutableList.of(
                "address", "user@organization.com",
                "type", "to",
                "locale", "en"
              ),
              "subject", ImmutableMap.of(
                "en", "Great sales!"
              ),
              "message", ImmutableMap.of(
                "en", "We've done great boys! Check out these numbers!"
              )
            )
          )
        )
      )
    );
    
    
       Alerts are linked to users on creation 
    dynamic properties = new ExpandoObject();
    properties.name = new {
      en = "<title of your alert>"
    };
    properties.query = new {
      dimensions = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_id = "< Type of burrito column id >"
        }
      },
      measures = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_id = "< Number of burritos column id >",
          aggregation = new {
            type = "sum"
          }
        }
      },
      where = new List<Object> {
        new {
          expression = "? in ?",
          parameters = new List<Object> {
            new {
              dataset_id = "< Burrito dataset id >",
              column_i = "< Type of burrito column id >"
            },
            new List<Object>{'Quesarito', 'Chicken baconito'}
          }
        }
      },
      having = new List<Object> {
        new {
          expression = "? >= ?",
          parameters = new List<Object> {
            new {
              dataset_id = "< Burrito dataset id >",
              column_id = "< Sold units column id >",
              aggregation = new {
                type = "sum"
              }
            },
            10000
          }
        }
      }
    };
    properties.frequency = new {
      unit = "day",
      quantity = 1
    };
    properties.channels = new List<Object> {
      new {
        type = "email",
        config = new {
          recipients = new List<Object> {
            new {
              address = "user@organization.com",
              type = "to",
              locale = "en"
            }
          },
          subject = new {
            en = "Great sales!"
          },
          message = new {
            en: "We've done great boys! Check out these numbers!"
          }
        }
      }
    };
    
    dynamic alert = client.create("alert", properties);
    
       Alerts are linked to users on creation 
    client.create('account',
      {
        name: { en: '<title of your alert>' },
        query: {
        dimensions: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Type of burrito column id >'
          }
        ],
        measures: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Number of burritos column id >',
            aggregation: {
              type: 'sum'
            }
          }
        ],
        where: [
          {
            expression: '? in ?',
            parameters: [
              {
                dataset_id: '< Burrito dataset id >',
                column_id: '< Type of burrito column id >'
              },
              ['Quesarito', 'Chicken baconito']
            ]
          }
        ],
        having: [
          {
            expression: '? >= ?',
            parameters: [
              {
                dataset_id: '< Burrito dataset id >',
                column_id: '< Sold units column id >',
                aggregation: {
                  type: 'sum'
                }
              },
              10000
            ]
          }
        ]
      },
        frequency: {
        unit: 'day',
        quantity: 1
      },
      channels: [
        {
          type: 'email',
          config: {
            recipients: [
              {
                address: 'user@organization.com',
                type: 'to',
                locale: 'en'
              }
            ],
            subject: {
              en: 'Great sales!'
            },
            message: {
              en: "We've done great boys! Check out these numbers!"
            }
          }
        }
      ]
    }
    );
    
       Alerts are linked to users on creation 
    <?php
    $alert = $client->create('alert',
      array (
        'name' => array (
          'en' => '<title of your alert>'
        ),
        'query' => array (
          'dimensions' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Type of burrito column id >'
            )
          ),
          'measures' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Number of burritos column id >',
              'aggregation' => array (
                'type' => 'sum'
              )
            )
          ),
          'where' => array (
            array (
              'expression' => '? in ?',
              'parameters' => array (
                array (
                  'dataset_id' => '< Burrito dataset id >',
                  'column_id' => '< Type of burrito column id >'
                ),
                array ('Quesarito', 'Chicken baconito')
              )
            )
          ),
          'having' => array (
            array (
              'expression' => '? >= ?',
              'parameters' => array (
                array (
                  'dataset_id' => '< Burrito dataset id >',
                  'column_id' => '< Sold units column id >',
                  'aggregation' => array (
                    'type' => 'sum'
                  )
                ),
              10000
              )
            )
          )
        )
        'frequency' => array (
          'unit' => 'day',
          'quantity' => 1
        ),
        'channels' => array (
          array (
            'type' => 'email',
            'config' => array (
              'recipients' => array (
                array (
                  'address' => 'user@organization.com',
                  'type' => 'to',
                  'locale' => 'en'
                )
              ),
              'subject' => array (
                'en' => 'Great sales!'
              ),
              'message' => array (
                'en' => "We've done great boys! Check out these numbers!"
              )
            )
          )
        )
      )
    
    );
    ?>
    
       Alerts are linked to users on creation 
    curl https://api.cumul.io/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "create",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "properties": {
      "name": { "en": "<title of your alert>" }
      "query": {
        "dimensions": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Type of burrito column id >"
          }
        ],
        "measures": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Number of burritos column id >",
            "aggregation": {
              "type": "sum"
            }
          }
        ],
        "where": [
          {
            "expression": "? in ?",
            "parameters": [
              {
                "dataset_id": "< Burrito dataset id >",
                "column_id": "< Type of burrito column id >"
              },
              ["Quesarito", "Chicken baconito"]
            ]
          }
        ],
        "having": [
          {
            "expression": "? >= ?",
            "parameters": [
              {
                "dataset_id": "< Burrito dataset id >",
                "column_id": "< Sold units column id >",
                "aggregation": {
                  "type": "sum"
                }
              },
              10000
            ]
          }
        ]
      },
      "frequency": { "unit": "day", "quantity": 1 }
      "channels": [
        {
          "type": "email",
          "config": {
            "recipients": [
              {
                "address": "user@organization.com",
                "type": "to",
                "locale": "en"
              }
            ],
            "subject": {
              "en": "Great sales!"
            },
            "message": {
              "en": "We've done great boys! Check out these numbers!"
            }
          }
        }
      ]
    }
    }
    EOF
    
    Create
    can be executed by:
    Logged-in (SSO) User

    Action: Update

       Update the frequency of an alert 
    JSONObject account = client.update("alert", "<your alert id>", 
      ImmutableMap.of(
        "frequency" , ImmutableMap.of(
          "unit", "week",
          "quantity", 1
        )
      ));
    
       Update the frequency of an alert 
    dynamic properties = new ExpandoObject();
    properties.frequency = new {
      unit = "week",
      quantity = 1
    };
    
    dynamic account = client.update("alert", "<your alert id>", properties);
    
       Update the frequency of an alert 
    client.update('alert',
      '<your alert id>',
      {
        frequency: {
          unit: 'week',
          quantity: 1
        }
      }
    )
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Update the frequency of an alert 
    <?php
    $user = $client->update('alert', '<your alert id>', 
      array (
        'frequency' => array (
          'unit' => 'week',
          'quantity' => 1
        )
      ));
    ?>
    
       Update the frequency of an alert 
    curl https://api.cumul.io/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "update",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your alert id>",
      "properties": {
        "frequency": { "unit": "week", "quantity": 1 }
      }
    }
    EOF
    
    Update
    can be executed by:
    Alert Owner

    Action: Get

       Retrieve all your alerts 
    JSONObject data = client.get("alert", 
      ImmutableMap.of(
    
      ));
    
    
       Retrieve all your alerts 
    dynamic query = new ExpandoObject();
    
    dynamic data = client.get("alert",     query);
    
    
       Retrieve all your alerts 
    client.get('alert', {})
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Retrieve all your alerts 
    <?php
    $user = $client->get('alert', 
      array (
    
      ));
    
    ?>
    
       Retrieve all your alerts 
    curl https://api.cumul.io/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "get",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "find": {}
    }
    EOF
    
    
    Get
    can be executed by:
    Alert Owner
    List
    can be executed by:
    Alert Owner

    Retrieving alerts.

    Action: Delete

       Delete an alert 
    client.delete("alert", "<your alert id>");
    
       Delete an alert 
    $client->delete("alert", "<your alert id>");
    
       Delete an alert 
    let promise = client.delete('alert', '<your alert id>');
    
       Delete an alert 
    <?php
    $client->delete('alert', '<your alert id>');
    ?>
    
       Delete an alert 
    curl https://api.cumul.io/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "delete",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your alert id>"
    }
    EOF
    
    Delete
    can be executed by:
    Alert Owner

    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.

    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

    Parameter
    Description
    id
    uuid
    Unique key of the authorization (automatically assigned)
    type
    string
    Authorization type. Either login, api or temporary. You can only create temporary authorizations with an API authorization.
    expiry
    datetime or string
    Date/time when this authorization will cease working. This is the hard (maximum) expiry time of the token, after which it will *always* invalidate. Defaults to 9999-12-31 (no expiry). We advise to set a short expiry time, eg. 24 hours.

    You can also use a duration string like 60 minutes or 1 day. The expiry will then be calculated from the current time.
    inactivity_interval
    integer or string
    Duration of inactivity (in seconds) after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). A value of 0 means no automatic invalidation due to inactivity (the token will only expire based on the value in expiry). Defaults to 0.

    We advise not to set the interval to a value smaller than 2 minutes, to avoid accidental invalidation for a dashboard that is still open, eg. when a heartbeat signal sent to the server is missed.

    You can also use a duration string like 5 minutes or 25 minutes.
    ip
    array[string]
    List of IP addresses or subnets. Both IPv4 and IPv6 IPs and subnets can be used. Leave empty to disable IP whitelisting. Eg.: ["123.45.67.89", "123.45.66.0/4", "2001:db8:0:1:1:1:1:1"]
    securables
    array[uuid]
    List of Securable identifiers to give access to. If empty, the authorization can be used to access all Securables to which the User from which the authorization derives has access. It is advised to always explicitly list all Securables. Eg.: ["4db23218-1bd5-44f9-bd2a-7e6051d69166", "f335be80-b571-40a1-9eff-f642a135b826"]
    filters
    array[object]
    List of data filters to apply when data queries are performed with this authorization. This can be used with multitenanted datasets to ensure end-clients can only access their own data.
    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
    Level to apply the filter. Possible values: global (row-level security, exclude specific rows from users for the complete dataset), chart (row-level security, exclude specific rows from users for a single chart), initialization (initialize an interactive filter within a dashboard to a particular value, but the end-user can override the filter value)
    securable_id
    uuid
    In case of global or chart filter:
    Dataset id to filter.
    column_id
    uuid
    In case of global or chart filter:
    Column id to filter.
    chart_id
    uuid
    In case of initialization or chart filter:
    Chart id to initialize.
    expression
    *
    Which filter to apply. Possible values: ? = ?, ? > ?, ? >= ?, ? < ?, ? <= ?, ? in ?, ? not in ?, ? is null, ? is not null.
    value
    string
    Value to insert in the filter.
    screenmode
    string
    Screen mode of dashboards to use. Either desktop, tablet, mobile, largeScreen, fixed. If empty, the window size will be used to determine the screen mode.
    locale_id
    string
    Locale of dashboards to use, if that locale is available. Eg. nl. This is a shorthand form to set the Authorization - Locale association. If empty, the optimal locale will be automatically determined
    timezone_id
    string
    Timezone id for dashboards to use, if that timezone id exists. This timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York.
    width
    string
    Optional width the dashboard should take, e.g. 800px.
    height
    string
    Optional height the dashboard should take, e.g. 600px.
    username
    string
    Viewer metadata: The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.
    name
    string
    Viewer metadata: name of the end-user.
    email
    string
    Viewer metadata: email address of the end-user.
    metadata
    object
    Use this parameter to set a parameter filter or specify optional Viewer metadata. This must be a valid JSON object with a maximum length of 10 000 characters. To clear a parameter (deactivate it on the dashboard), pass in the special value {"clear": true}
    theme
    object
    Optional JSON definition of a theme to apply to the dashboard
    css
    string
    Optional CSS override to apply to the dashboard. The CSS gets appended to the existing CSS overrides in the dashboard.
    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 Plugin account id for which you want to override properties as property name.
    base_url
    string
    (optional) The new base URL that will be called.
    host
    string
    (optional) The new host value that will be sent as X-Host header to the Plugin.
    key
    string
    (optional) The new key value that will be sent as X-Key header to the Plugin.
    token
    string
    (optional) The new token value that will be sent as X-Token header to the Plugin.
    table
    string
    (optional) The new canonical dataset identifier defined in the Plugin to retrieve data from.
    account_overrides
    object
    < account id >
    object
    The database account id for which you want to override properties as property name.
    host
    string
    (optional) The new database host to connect to. The database must be of the same type as the originally configured database.
    port
    string
    (optional) The new port to connect to.
    user
    string
    (optional) The new user to use when connecting.
    password
    string
    (optional) The new password to use when connecting.
    schema
    string
    (optional) The new schema to retrieve data from. Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value to both schema and database
    database
    string
    (optional) the new database to retrieve data from. Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value to both schema and database
    table
    string
    (optional) The new table to retrieve data from.
    datasets
    object
    (optional) List of dataset-level overrides. Useful if you want to override only a single table in your dashboard or if you have a separate table per client. The SQL query of the dataset can also be overridden if it's a SQL dataset within Cumul.io. Allowing you to call stored procedures for example.
    < dataset id >
    object
    The dataset (securable) ID that you want to override.
    table
    string
    (optional) The new table to connect to
    schema
    string
    (optional) The new schema to connect to.
    sql
    string
    (optional) The new SQL statement to use. NOTE: the columns returned in the new query need to conform to the same schema as the original dataset.
    last_used_at
    datetime
    (Read-only) Timestamp of the last API call of this authorization. Can be delayed up to 5 minutes.

    Actions

    Create
    Get
    List
    Delete

    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 API token of an organization owner which has access to your organization's resources 
    JSONObject user = client.create("user",
    
      ImmutableMap.of(
        "name" , "Technical User",
        "email" , "technical-user@cumul.io",
        "password" , "... random password ..."
      ));
    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 API token of an organization owner which has access to your organization's resources 
    dynamic properties = new ExpandoObject();
    properties.name = "Technical User";
    properties.email = "technical-user@cumul.io";
    properties.password = "... random password ...";
    
    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 API token of an organization owner which has access to your organization's resources 
    client.create('user',
      {
      name: 'Technical User',
      email: 'technical-user@cumul.io',
      password: '... random password ...'
    }
    
    )
      .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 API token of an organization owner which has access to your organization's resources 
    <?php
    $user = $client->create('user',
    
      array (
        'name' => 'Technical User',
        'email' => 'technical-user@cumul.io',
        'password' => '... random password ...'
      )
    
    );
    $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 API token of an organization owner which has access to your organization's 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 ..."
    }
    }
    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" , "24 hours",
        "inactivity_interval", "10 minutes",
        "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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    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: '24 hours',
      inactivity_interval: '10 minutes',
      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' => '24 hours',
        'inactivity_interval' => '10 minutes',
        '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": "24 hours",
      "inactivity_interval": "10 minutes",
      "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, and clearing another Parameter using the special value ImmutableMap.of("clear", true). 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" , "24 hours",
        "inactivity_interval", "10 minutes",
        "metadata" , ImmutableMap.of(
          "Country", ImmutableList.of(
            "Spain"
          ),
          "< Parameter name >" , ImmutableList.of(
            "< value to apply >",
            "< other value to apply >"
          ),
          "< Parameter to clear >", ImmutableMap.of(
            "clear", true
          )
        )
      ));
    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, and clearing another Parameter using the special value {clear = true}.  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 = "24 hours";
    properties.inectivity_interval = "10 minutes";
    properties.metadata = new {
          Country = new List<Object> {
            "Spain"
          },
          "< Parameter name >" = new List<Object> {
            "< value to apply >",
            "< other value to apply >"
          },
          "< Parameter to clear >" = new {
            clear = true
          }
        };
    
    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, and clearing another Parameter using the special value {clear: true}. 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: '24 hours',
      inactivity_interval: '10 minutes',
      metadata: {
        Country: ['Spain'],
        '< Parameter name >': [
          '< value to apply >',
          '< other value to apply >'
        ],
        '< Parameter to clear >': {
          clear: true
        }
      }
    }
    
    )
      .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, and clearing another Parameter using the special value array('clear' => true). 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' => '24 hours',
        'inactivity_interval' => '10 minutes',
        'metadata' => array (
          'Country' => array (
            'Spain'
          ),
          '< Parameter name >' => array (
            '< first value to apply >',
            '< Second value to apply >'
          ),
          '< Parameter to clear >' => array (
            'clear' => true
          )
        )
      )
    
    );
    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, and clearing another Parameter using the special value {"clear": true}. 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": "24 hours",
        "inactivity_interval": "10 minutes",
        "metadata": {
          "Country": ["Spain"],
          "< Parameter name >": [
            "< value to apply >",
            "< other value to apply >"
          ],
          "< Parameter to clear >": {
            "clear": true
          }
        }
      }
    }
    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 JSONObject authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >",
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset 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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset 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: '24 hours',
      inactivity_interval: '10 minutes',
      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' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset 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": "24 hours",
        "inactivity_interval": "10 minutes",
        "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 JSONObject authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >",
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset 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 an object 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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset 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 an object 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: '24 hours',
      inactivity_interval: '10 minutes',
      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 an object 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' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset 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 an object 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": "24 hours",
        "inactivity_interval": "10 minutes",
        "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 an object 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 JSONObject authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >", 
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("filters", ImmutableList.of(
        ImmutableMap.builder()
        .put("clause",       "where")
        .put("origin",       "initialization")
        .put("chart_id",     "< chart id of a filter object 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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.filters = new List<dynamic> {
      new {
        clause = "where",
        origin = "initialization",
        chart_id = "< chart id of a filter object 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: '24 hours',
      inactivity_interval: '10 minutes',
      filters: [
        {
          clause: 'where',
          origin: 'initialization',
          chart_id: '< chart id of a filter object 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' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'filters' => array(
        array(
          'clause'     => 'where',
          'origin'     => 'initialization',
          'chart_id'   => '< chart id of a filter object 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": "24 hours",
        "inactivity_interval": "10 minutes",
        "filters": [
          {
            clause: "where",
            origin: "initialization",
            chart_id: "< chart id of a filter object 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. Besides setting initialization filters on filter objects, you can also set them on charts. In this case you need to supply a column_id and securable_id. Filter values always need to consist of an array.
    
    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 authorization = client.create("authorization", ImmutableMap.builder()
      .put("type","temporary")
      .put("expiry", "24 hours")
      .put("inactivity_interval", "10 minutes")
      .put("securables", ImmutableList.of(
        "< dashboard id >", 
        "< dataset id of a dataset used in the dashboard >",
        "< dataset id of a dataset used in the dashboard >"
      ))
      .put("filters", ImmutableList.of(
        ImmutableMap.builder()
        .put("clause",       "where")
        .put("origin",       "initialization")
        .put("chart_id",     "< chart id of a chart object contained in the dashboard >")
        .put("expression",   "? = ?")
        .put("column_id",    "< id of the column you want to filter on (usually in category slot) >")
        .put("securable_id", "< id of the dataset that the column belongs to >")
        .put("value",        ImmutableList.of(
          "<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. Besides setting initialization filters on filter objects, you can also set them on charts. In this case you need to supply a column_id and securable_id. Filter values always need to consist of an array.
    
    Cumulio client = new Cumulio("< Your API key >", "< Your API token >");
    
    dynamic properties = new ExpandoObject();
    properties.type = "temporary";
    properties.expiry = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.securables = new List<String> {
      "< dashboard id >", 
      "< dataset id of a dataset used in the dashboard >",
      "< dataset id of a dataset used in the dashboard >"
    };
    properties.filters = new List<dynamic> {
      new {
        clause = "where",
        origin = "initialization",
        chart_id = "< chart id of a chart object contained in the dashboard >",
        expression = "? = ?",
        column_id = "< id of the column to apply the filter to (usually the category) >",
        securable_id = "< id of the dataset that the column belongs to >",
        value = new List<string> {
          "< 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. Besides setting initialization filters on filter objects, you can also set them on charts. In this case you need to supply a column_id and securable_id. Filter values always need to consist of an array.
    
    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: '24 hours',
      inactivity_interval: '10 minutes',
      filters: [
        {
          clause: 'where',
          origin: 'initialization',
          chart_id: '< chart id of a chart object contained in the dashboard >',
          expression: '? = ?',
          column_id: '< id of the column to apply the filter to (usually the category) >',
          securable_id: '< id of the dataset that the column belongs to >',
          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. Besides setting initialization filters on filter objects, you can also set them on charts. In this case you need to supply a column_id and securable_id. Filter values always need to consist of an array.
    
    <?php
    include('cumulio.php');
    $client = Cumulio::initialize('< your API key >', '< your API token >');
    
    $authorization = $client->create('authorization', array(
      'type' => 'temporary',
      'expiry' => '24 hours',
      'inactivity_interval' => '10 minutes',
      'securables' => array(
        '< dashboard id >', 
        '< dataset id of a dataset used in the dashboard >',
        '< dataset id of a dataset used in the dashboard >'
      ),
      'filters' => array(
        array(
          'clause'       => 'where',
          'origin'       => 'initialization',
          'chart_id'     => '< chart id of a chart object contained in the dashboard >',
          'expression'   => '? = ?',
          'column_id'    => '< id of the column to apply the filter to (usually the category) >',
          'securable_id' => '< id of the dataset that the column belongs to >'
          'value'        => array(
            '< 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. Besides setting initialization filters on filter objects, you can also set them on charts. In this case you need to supply a column_id and securable_id. Filter values always need to consist of an array.
    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "filters": [
          {
            clause: "where",
            origin: "initialization",
            chart_id: "< chart id of a chart object contained in the dashboard >",
            expression: "? = ?",
            column_id: '< id of the column to apply the filters to >',
            securable_id: '< id of the dataset that the column belongs to >',
            value: [
              "< value to be applied to the expression >"
            ]
          }
        ]
      }
    }
    EOF
    
       Temporary tokenAn example showing how to apply theme overrides to a temporary token
    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" , "24 hours",
        "inactivity_interval", "10 minutes",
        "theme", ImmutableMap.of(
          ... JSON theme definition ...
        ),
        "metadata" , ImmutableMap.of(
          "internalid" , "user19"
        )
    ));
    System.out.println("Success! %s%n", authorization);
    
         Temporary token   An example showing how to apply theme overrides to a temporary token  
    dynamic properties = new ExpandoObject();
    dynamic theme = new ExpandoObject();
    
    // Create theme definition here
    // ...
    
    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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.theme = theme;
    properties.metadata = new {
            internalid = "user19"
        };
    
    dynamic authorization = client.create("authorization",    properties);
    Console.WriteLine("Success!", authorization);
    
         Temporary token   An example showing how to apply theme overrides to a temporary 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: '24 hours',
      inactivity_interval: '10 minutes',
      theme: { ... theme definition },
      metadata: {
        internalid: 'user19'
      }
    })
      .then(function(authorization) {
        console.log('Success!', authorization);
      });
    
         Temporary token  An example showing how to apply theme overrides to a temporary token
    
    <?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' => '24 hours',
        'inactivity_interval' => '10 minutes',
        'theme' => array(
          ... JSON theme definition ...
        ),
        'metadata' => array (
          'internalid' => 'user19'
        )
      )
    );
    print("Success! { $authorization }");
    ?>
    
         Temporary token   An example showing how to apply theme overrides to a temporary 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": "temporary",
        "securables": [
          "< dashboard id >",
          "< dataset id of a dataset used in the dashboard >",
          "< dataset id of a dataset used in the dashboard >"
        ],
        "expiry": "24 hours",
        "inactivity_interval": "10 minutes",
        "theme": {
          ... JSON theme definition ...
        },
        "metadata": {
          "internalid": "user19"
        }
      }
    }
    EOF
    
    
         Temporary token  An example showing how to apply CSS overrides to a temporary token. Provided CSS is appended to the existing CSS overrides 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" , "24 hours",
        "inactivity_interval", "10 minutes",
        "css", "body { background-color: red !important; }",
        "metadata" , ImmutableMap.of(
          "internalid" , "user19"
        )
    ));
    System.out.println("Success! %s%n", authorization);
    
         Temporary token   An example showing how to apply CSS overrides to a temporary token. Provided CSS is appended to the existing CSS overrides 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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.css = "body { background-color: red !important; }";
    properties.metadata = new {
            internalid = "user19"
        };
    
    dynamic authorization = client.create("authorization",    properties);
    Console.WriteLine("Success!", authorization);
    
         Temporary token   An example showing how to apply CSS overrides to a temporary token. Provided CSS is appended to the existing CSS overrides 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: '24 hours',
      inactivity_interval: '10 minutes',
      css: 'body { background-color: red !important; }',
      metadata: {
        internalid: 'user19'
      }
    })
      .then(function(authorization) {
        console.log('Success!', authorization);
      });
    
         Temporary token  An example showing how to apply CSS overrides to a temporary token. Provided CSS is appended to the existing CSS overrides 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' => '24 hours',
        'inactivity_interval' => '10 minutes',
        'css' => 'body { background-color: red !important; }',
        'metadata' => array (
          'internalid' => 'user19'
        )
      )
    );
    print("Success! { $authorization }");
    ?>
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.
    
    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "css": "body { background-color: red !important; }",
        "metadata": {
          "internalid": "user19"
        }
      }
    }
    EOF
    
    
         Temporary token An example showing how to apply dataset level overrides when using account_overrides.
    
    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" , "24 hours",
      "inactivity_interval", "10 minutes",
      "css", "body { background-color: red !important; }",
      "account_overrides" , ImmutableMap.of(
        "< account ID >" , ImmutableMap.of(
          "datasets", ImmutableMap.of(
            "< dataset ID >", ImmutableMap.of(
              "table": "< my new table name >"
            )
          )
        )
      )
    ));
    System.out.println("Success! %s%n", authorization);
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.  
    
    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 = "24 hours";
    properties.inactivity_interval = "10 minutes";
    properties.css = "body { background-color: red !important; }";
    properties.account_overrides = new {
      < account ID > = new {
        datasets = new {
          < dataset ID > = new {
            table = "< my new table name >"
          }
        }
      }
    };
    
    dynamic authorization = client.create("authorization",    properties);
    Console.WriteLine("Success!", authorization);
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.  
    
    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: '24 hours',
        inactivity_interval: '10 minutes',
        css: 'body { background-color: red !important; }',
        account_overrides: {
          '< account ID >': {
            datasets: {
              '< dataset ID >': {
                table: '< my new table name >'
              }
            }
          }
        }
      }
    
    )
      .then(function(authorization) {
        console.log('Success!', authorization);
      });
    
         Temporary token An example showing how to apply dataset level overrides when using account_overrides.
    
    <?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' => '24 hours',
        'inactivity_interval' => '10 minutes',
        'css' => 'body { background-color: red !important; }',
        'account_overrides' => array (
          '< account ID >' => array (
            'datasets' => array (
              '< dataset ID >' => array (
                'table' => '< my new table name >'
              )
            )
          )
        )
      )
    
    );
    print("Success! { $authorization }");
    ?>
    
         Temporary token  An example showing how to apply dataset level overrides when using account_overrides.
    
    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": "24 hours",
        "inactivity_interval": "10 minutes",
        "css": "body { background-color: red !important; }",
        "account_overrides": {
          "< account ID >": {
            "datasets": {
              "< dataset ID >": {
                "table": "< my new table name >"
              }
            }
          }
        }
      }
    }
    EOF
    
    
    Create
    can be executed by:
    Logged-in User

    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",
          "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
       }
      ]
    }
    
    Get
    can be executed by:
    Authorization Owner
    List
    can be executed by:
    Authorization Owner

    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
    can be executed by:
    Authorization Owner

    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.

    %3 <!-- User --> User User <!-- Authorization --> Authorization Authorization <!-- User->Authorization --> User->Authorization <!-- Locale --> Locale Locale <!-- Locale->Authorization --> Locale->Authorization

    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
    
    
    Authorization
    Locale
    Associate
    requires:
    Authorization Owner

    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

    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 >"
        )
      ));
    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 >"
        };
    
    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 >'
        ]
    }
    
    )
      .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 >'
        )
      )
    
    );
    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 >"
      ]
    }
    }
    EOF
    # result format of the authorization contains the user_id 
    {
     ... 
     "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
    ...
    }
    
    Authorization
    User
    Associate
    requires:
    Authorization Owner

    When associating authorizations there are two things to keep in mind. First is that authorizations 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.

    Column

    A column contains the metadata (type, name) of a specific column in a dataset.

    Properties

    Parameter
    Description
    id
    uuid
    Unique key of the column (automatically assigned)
    name
    localized
    Column name
    order
    integer
    Sorting order of this column (eg. 0, 1, 2). This is a required field.
    source_name
    string
    The original name of the column. This property will be set automatically when uploading a dataset or when creating a dataset via the data push API. You can set it manually when creating a column via API, but the value cannot be changed afterwards.
    type
    string
    Column type (numeric, datetime, hierarchy or spatial). Can be modified at any time with immediate effect for all historical and new data.
    subtype
    string
    For columns of type spatial: indicates the subtype of the column. Can be either topography or coordinates.
    format
    string
    Default formatting, used to present data in charts or tables.
    informat
    string
    Default informat, used to interpret raw input data. Can be modified at any time with immediate effect for all historical and new data.
    • For numeric type: numeric or percentage
    • For hierarchy type: hierarchy
    • For datetime type, either:
      • YYYY-MM-DD HH:mm:ss.SSS (ISO-style)
      • MM-DD-YYYY HH:mm:ss.SSS (US-style)
      • DD-MM-YYYY HH:mm:ss.SSS (EU-style)
      • X (UNIX timestamp, seconds since 1/1/1970)
      • x (UNIX timestamp, milliseconds since 1/1/1970)
      The actual data can have a different input format (eg. different separators, named months, ...). The informat only indicates the order of parsing.
    hierarchy_enabled
    boolean
    When this boolean is set, hierarchies can be used in the dashboard editor and dashboards. If you are experimenting with Hierarchies you can keep this disabled until you want them to be visible/usable. If you only use hierarchies to override colors/names/ordering, keep it disabled. More information can be found in Hierarchy
    colors_enabled
    boolean
    When this boolean is set, colors set via the hierarchy endpoint will override colors in the dashboard. This allows you to add colors to data values to make sure that the dashboard colors are data driven. More information can be found in Hierarchy
    ordering_enabled
    boolean
    (Coming soon) You can set a custom order for values via the hierarchy which can be disabled/enabled using this boolean. These can then be used to override ordering in the dashboard. This feature is currently in progress Hierarchy
    color
    string
    Default color for the column, in hexadecimal string notation, eg. #45AB7C
    isLabel
    boolean
    Whether this column contains labels used for topographic features (eg. municipality names). Defaults to false.
    minBound
    datetime
    (Read-only) Smallest datetime over all rows
    maxBound
    datetime
    (Read-only) Largest datetime over all rows
    cardinality
    integer
    (Read-only) Number of distinct values within this column. Note: this value is approximate to within 1.625%.
    lowestLevel
    integer
    (Datetime only) Most precise datetime level used in the source data (1 - year, 9 - millisecond). The dashboard editor will only allow these levels to be used as slots.
    minimum
    integer
    (Read-only, numeric only) Smallest value over all rows
    maximum
    integer
    (Read-only, numeric only) Largest value over all rows
    expression
    string
    Derived column expression. Must be a valid expression.
    version
    integer
    (Read-only) Version indicator, increments on each change
    width
    integer
    Data table column header width (in pixels). Defaults to 170.

    Actions

    Create
    Get
    List
    Delete
    Update
    Associate
    Dissociate

    Action: Create

       Creating a column of type hierarchy, note that you need to provide a unique order index. In this case the order is 0 since we want our first column to appear first. 
    JSONObject column = client.create("column",
    
      ImmutableMap.of(
        "name" , ImmutableMap.of(
          "en" , "Burrito name"
        ),
        "type" , "hierarchy",
        "order" , "0",
        "format" , "",
        "informat" , "hierarchy",
        "color" , "#a945aa"
      ));
    System.out.println("Success! %s%n", column);
    
       Creating a column of type hierarchy, note that you need to provide a unique order index. In this case the order is 0 since we want our first column to appear first. 
    dynamic properties = new ExpandoObject();
    properties.name = new {
          en = "Burrito name"
        };
    properties.type = "hierarchy";
    properties.order = "0";
    properties.format = "";
    properties.informat = "hierarchy";
    properties.color = "#a945aa";
    
    dynamic column = client.create("column",    properties);
    Console.WriteLine("Success!", column);
    
       Creating a column of type hierarchy, note that you need to provide a unique order index. In this case the order is 0 since we want our first column to appear first. 
    client.create('column',
      {
        name: {
            en: 'Burrito name'
        },
        type: 'hierarchy',
        order: 0,
        format: '',
        informat: 'hierarchy',
        color: '#a945aa'
    }
    
    )
      .then(function(column) {
        console.log('Success!', column);
      });
    
       Creating a column of type hierarchy, note that you need to provide a unique order index. In this case the order is 0 since we want our first column to appear first. 
    <?php
    $column = $client->create('column',
    
      array (
        'name' => array (
          'en' => 'Burrito name'
        ),
        'type' => 'hierarchy',
        'order' => '0',
        'format' => '',
        'informat' => 'hierarchy',
        'color' => '#a945aa'
      )
    
    );
    print("Success! { $column }");
    ?>
    
       Creating a column of type hierarchy, note that you need to provide a unique order index. In this case the order is 0 since we want our first column to appear first. 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "create",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "properties": {
      "name": {
        "en": "Burrito name"
      },
      "type": "hierarchy",
      "order": 0,
      "format": "",
      "informat": "hierarchy",
      "color": "#a945aa"
    }
    }
    EOF
    
    
       Creating a date column, note that we use 1 as order since 0 is already taken and orders need to be unique. If we would use an overlapping index with the first column, the resulting dataset will not work properly. 
    JSONObject column = client.create("column",
    
      ImmutableMap.of(
        "name" , ImmutableMap.of(
          "en" , "Burrito production date"
        ),
        "type" , "datetime",
        "order" , "1",
        "format" , "%d-%m-%Y",
        "informat" , "YYYY-MM-DD HH:mm:ss.SSS"
      ));
    System.out.println("Success! %s%n", column);
    
       Creating a date column, note that we use 1 as order since 0 is already taken and orders need to be unique. If we would use an overlapping index with the first column, the resulting dataset will not work properly. 
    dynamic properties = new ExpandoObject();
    properties.name = new {
          en = "Burrito production date"
        };
    properties.type = "datetime";
    properties.order = "1";
    properties.format = "%d-%m-%Y";
    properties.informat = "YYYY-MM-DD HH:mm:ss.SSS";
    
    dynamic column = client.create("column",    properties);
    Console.WriteLine("Success!", column);
    
       Creating a date column, note that we use 1 as order since 0 is already taken and orders need to be unique. If we would use an overlapping index with the first column, the resulting dataset will not work properly. 
    client.create('column',
      {
        name: {
            en: 'Burrito production date'
        },
        type: 'datetime',
        order: 1,
        format: '%d-%m-%Y',
        informat: 'YYYY-MM-DD HH:mm:ss.SSS'
    }
    
    )
      .then(function(column) {
        console.log('Success!', column);
      });
    
       Creating a date column, note that we use 1 as order since 0 is already taken and orders need to be unique. If we would use an overlapping index with the first column, the resulting dataset will not work properly. 
    <?php
    $column = $client->create('column',
    
      array (
        'name' => array (
          'en' => 'Burrito production date'
        ),
        'type' => 'datetime',
        'order' => '1',
        'format' => '%d-%m-%Y',
        'informat' => 'YYYY-MM-DD HH:mm:ss.SSS'
      )
    
    );
    print("Success! { $column }");
    ?>
    
       Creating a date column, note that we use 1 as order since 0 is already taken and orders need to be unique. If we would use an overlapping index with the first column, the resulting dataset will not work properly. 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "create",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "properties": {
      "name": {
        "en": "Burrito production date"
      },
      "type": "datetime",
      "order": 1,
      "format": "%d-%m-%Y",
      "informat": "YYYY-MM-DD HH:mm:ss.SSS"
    }
    }
    EOF
    
    
    Create
    can be executed by:
    Logged-in User

    Any user with an API token can create a column. In order to use the column you will have to associate it to a dataset later on.

    Action: Update

       Example of updating the order of a column to put it in front, make sure however that order 0 is not taken yet! Else you have to move that column first. 
    JSONObject column = client.update("column", "<your column id>", 
      ImmutableMap.of(
        "id" , "< my column id >",
        "order" , "0"
      ));
    
       Example of updating the order of a column to put it in front, make sure however that order 0 is not taken yet! Else you have to move that column first. 
    dynamic properties = new ExpandoObject();
    properties.id = "< my column id >";
    properties.order = "0";
    
    dynamic column = client.update("column", "<your column id>", );
    
       Example of updating the order of a column to put it in front, make sure however that order 0 is not taken yet! Else you have to move that column first. 
    client.update('column',
      '<your column id>',
      {
        id: '< my column id >',
        order: 0
    }
    )
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Example of updating the order of a column to put it in front, make sure however that order 0 is not taken yet! Else you have to move that column first. 
    <?php
    $user = $client->update('column', '<your column id>', 
      array (
        'id' => '< my column id >',
        'order' => '0'
      ));
    ?>
    
       Example of updating the order of a column to put it in front, make sure however that order 0 is not taken yet! Else you have to move that column first. 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "update",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your column id>",
      "properties": {
      "id": "< my column id >",
      "order": 0
    }
    }
    EOF
    
       Example where we change the UI representation of the date format 
    JSONObject column = client.update("column", "<your column id>", 
      ImmutableMap.of(
        "id" , "< my column id >",
        "format" , "DD-MM-YYYY"
      ));
    
       Example where we change the UI representation of the date format 
    dynamic properties = new ExpandoObject();
    properties.id = "< my column id >";
    properties.format = "DD-MM-YYYY";
    
    dynamic column = client.update("column", "<your column id>", );
    
       Example where we change the UI representation of the date format 
    client.update('column',
      '<your column id>',
      {
        id: '< my column id >',
        format: 'DD-MM-YYYY'
    }
    )
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Example where we change the UI representation of the date format 
    <?php
    $user = $client->update('column', '<your column id>', 
      array (
        'id' => '< my column id >',
        'format' => 'DD-MM-YYYY'
      ));
    ?>
    
       Example where we change the UI representation of the date format 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "update",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your column id>",
      "properties": {
      "id": "< my column id >",
      "format": "DD-MM-YYYY"
    }
    }
    EOF
    
    Update
    can be executed by:
    Securable Modifier

    Only users who have write access to the dataset to which the column is associated can update the column.

    Action: Get

       Retrieve a dataset and the columns that belong to it 
    JSONObject data = client.get("securable", 
      ImmutableMap.of(
        "where" , ImmutableMap.of(
          "type" , "dataset",
          "id" , "<id of your dataset>"
        ),
        "include" , ImmutableList.of(
    
          ImmutableMap.of(
            "model" , "Column"
          )
        )
      ));
    
    
       Retrieve a dataset and the columns that belong to it 
    dynamic query = new ExpandoObject();
    query.where = new {
          type = "dataset",
          id = "<id of your dataset>"
        };
    query.include = new List<Object> {
    
          new {
            model = "Column"
          }
        };
    
    dynamic data = client.get("securable",     query);
    
    
       Retrieve a dataset and the columns that belong to it 
    client.get('securable', {
        where: {
            type: 'dataset',
            id: '<id of your dataset>'
        },
        include: [
            {
                model: 'Column'
            }
        ]
    })
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Retrieve a dataset and the columns that belong to it 
    <?php
    $user = $client->get('securable', 
      array (
        'where' => array (
          'type' => 'dataset',
          'id' => '<id of your dataset>'
        ),
        'include' => array (
    
          array (
            'model' => 'Column'
          )
        )
      ));
    
    ?>
    
       Retrieve a dataset and the columns that belong to it 
    curl https://api.cumul.io/0.1.0/securable  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "get",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "find": {
      "where": {
        "type": "dataset",
        "id": "<id of your dataset>"
      },
      "include": [
        {
          "model": "Column"
        }
      ]
    }
    }
    EOF
    
    
       Retrieve a specific column and the dataset it is linked to 
    JSONObject data = client.get("column", 
      ImmutableMap.of(
        "where" , ImmutableMap.of(
          "id" , "<id of your column>"
        ),
        "include" , ImmutableList.of(
    
          ImmutableMap.of(
            "model" , "Securable"
          )
        )
      ));
    
    
       Retrieve a specific column and the dataset it is linked to 
    dynamic query = new ExpandoObject();
    query.where = new {
          id = "<id of your column>"
        };
    query.include = new List<Object> {
    
          new {
            model = "Securable"
          }
        };
    
    dynamic data = client.get("column",     query);
    
    
       Retrieve a specific column and the dataset it is linked to 
    client.get('column', {
        where: {
            id: '<id of your column>'
        },
        include: [
            {
                model: 'Securable'
            }
        ]
    })
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Retrieve a specific column and the dataset it is linked to 
    <?php
    $user = $client->get('column', 
      array (
        'where' => array (
          'id' => '<id of your column>'
        ),
        'include' => array (
    
          array (
            'model' => 'Securable'
          )
        )
      ));
    
    ?>
    
       Retrieve a specific column and the dataset it is linked to 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "get",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "find": {
      "where": {
        "id": "<id of your column>"
      },
      "include": [
        {
          "model": "Securable"
        }
      ]
    }
    }
    EOF
    
    
       Example of the return structure of the query above 
    {
      "count": 1,
      "rows": [
        {
          "id": "6ef3f802-7b17-4ac6-af2b-e86e7c058cd9",
          "name": {
            "en": "Acquisition"
          },
          "order": 4,
          "type": "hierarchy",
          "format": "",
          "informat": "hierarchy",
          "color": null,
          "minBound": null,
          "maxBound": null,
          "lowestLevel": 0,
          "highestLevel": 0,
          "minimum": null,
          "maximum": null,
          "created_at": "2018-08-30T11:44:20.234Z",
          "updated_at": "2018-08-30T11:44:20.923Z",
          "securable_id": "b06511f3-8cae-48f4-858a-ca409c065640",
          "expression": null,
          "width": 170,
          "source_name": null,
          "derivation": null,
          "version": 3,
          "cardinality": 9,
          "isLabel": false,
          "aggregation_type": "sum",
          "aggregation_id": null,
          "subtype": null,
          "hierarchy_enabled": false,
          "ordering_enabled": false,
          "colors_enabled": true
        },
        {
          ...
        },
        ...
      ]
    }
    
    Get
    can be executed by:
    Securable Reader
    List
    can be executed by:
    Securable Reader

    Only users who have read access to the dataset to which the column is associated can retrieve the columns of that dataset.

    Action: Delete

       Delete the column 
    client.delete("column", "<your column id>");
    
       Delete the column 
    $client->delete("column", "<your column id>");
    
       Delete the column 
    let promise = client.delete('column', '<your column id>');
    
       Delete the column 
    <?php
    $client->delete('column', '<your column id>');
    ?>
    
       Delete the column 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "delete",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your column id>"
    }
    EOF
    
    Delete
    can be executed by:
    Securable Modifier

    Delete a column by providing the id of the group.

    Associations

    %3 <!-- Dashboard --> Dashboard Dashboard <!-- Securable --> Securable Securable <!-- Dashboard->Securable --> Dashboard->Securable <!-- Dataset --> Dataset Dataset <!-- Dataset->Securable --> Dataset->Securable <!-- Column --> Column Column <!-- Securable->Column --> Securable->Column <!-- Column->Column --> Column->Column <!-- HierarchyLevel --> HierarchyLevel HierarchyLevel <!-- HierarchyLevel->Column --> HierarchyLevel->Column

    Associate: Column

       Link one dataset to another by associating their columns 
    client.associate("column", "<id of column 1>", "Joins", "<id of column 2>",
        ImmutableMap.of(
            "type", "lookup"
        )
    );
    
       Link one dataset to another by associating their columns 
    dynamic properties = new ExandoObject();
    properties.type = "lookup"; 
    
    client.associate("column", "<id of column 1>", "Joins", "<id of column 2>", properties);
    
       Link one dataset to another by associating their columns 
    let promise = client.associate('column', '<id of column 1>', { role: 'Joins', id: '<id of column 2>' }, {
        type: 'lookup'
    });
    
       Link one dataset to another by associating their columns 
    <?php
    $client->associate('column', '<id of column 1>', 'Joins', '<id of col 2>', , 
        array (
        'type' => 'lookup'
    ));
    ?>
    
       Link one dataset to another by associating their columns 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "associate",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<id of col 1>",
      "properties": {
          "type": "lookup"
      },
      "resource": {
        "role": "Joins",
        "id": "<id of col 2>"
      }
    }
    EOF
    
    Column
    Column

    In Cumul.io you can link two datasets to create a join betweeen them. You can create joins via API by associating the columns of the 2 datasets to link. Make sure the direction of the link between the datasets is many-to-one. Joins with multiple criteria can be set by just associating more than one set of columns.

    Associate: Dataset

       Add a column to your dataset (you have to create the column first) 
    client.associate("securable", "<your securable id>", "Columns", "<  column id>");
    
       Add a column to your dataset (you have to create the column first) 
    
    client.associate("securable", "<your securable id>", "Columns", "<  column id>");
    
       Add a column to your dataset (you have to create the column first) 
    let promise = client.associate('securable', '<your securable id>', {
        role: 'Columns',
        id: '<  column id>'
    });
    
       Add a column to your dataset (you have to create the column first) 
    <?php
    $client->associate('securable', '<your securable id>', 'Columns', '<  column id>', );
    ?>
    
       Add a column to your dataset (you have to create the column first) 
    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": "Columns",
        "id": "<  column id>"
      }
    }
    EOF
    
    Dataset
    Column
    Associate
    requires:
    Securable Modifier

    Columns contain the information of a column (not the data) within your datasets. When preparing your columns, be careful that when you upload data with the 'data' endpoint that the amount of columns corresponds to the data structure you will upload.

    Associate: HierarchyLevel

       Add a hierarchylevel to a column 
    client.associate("hierarchylevel", "<your hierarchylevel id>", "Column", "<column id>");
    
       Add a hierarchylevel to a column 
    
    client.associate("hierarchylevel", "<your hierarchylevel id>", "Column", "<column id>");
    
       Add a hierarchylevel to a column 
    let promise = client.associate('hierarchylevel', '<your hierarchylevel id>', {
        role: 'Column',
        id: '<column id>'
    });
    
       Add a hierarchylevel to a column 
    <?php
    $client->associate('hierarchylevel', '<your hierarchylevel id>', 'Column', '<column id>', );
    ?>
    
       Add a hierarchylevel to a column 
    curl https://api.cumul.io/0.1.0/hierarchylevel  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "associate",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your hierarchylevel id>",
      "resource": {
        "role": "Column",
        "id": "<column id>"
      }
    }
    EOF
    
    Column
    HierarchyLevel

    In Cumul.io all columns which deal with text values are of type hierarchy. On such a hierarchy column you can build a hierarchy out of your existing data values. To do so you first need to create hierarchy levels and associate them with a column.

    Dissociate

       Dissociate a column from a securable 
    client.dissociate("column", "<your column id>", "Securables", "<id of your securable>");
    
       Dissociate a column from a securable 
    client.dissociate("column", "<your column id>", "Securables", "<id of your securable>");
    
       Dissociate a column from a securable 
    let promise = client.dissociate('column', '<your column id>', {
        role: 'Securables',
        id: '<id of your securable>'
    });
    
       Dissociate a column from a securable 
    <?php
    $client->associate('column', '<your column id>', "Securables", "<id of your securable>");
    ?>
    
       Dissociate a column from a securable 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "dissociate",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your column id>",
      "resource": {
      "role": "Securables",
      "id": "<id of your securable>"
    }
    }
    EOF
    
       Dissociate a hierarchylevel from a column 
    client.dissociate("column", "<your column id>", "HierarchyLevels", "<id of your hierarchylevel>");
    
       Dissociate a hierarchylevel from a column 
    client.dissociate("column", "<your column id>", "HierarchyLevels", "<id of your hierarchylevel>");
    
       Dissociate a hierarchylevel from a column 
    let promise = client.dissociate('column', '<your column id>', {
        role: 'HierarchyLevels',
        id: '<id of your hierarchylevel>'
    });
    
       Dissociate a hierarchylevel from a column 
    <?php
    $client->associate('column', '<your column id>', "HierarchyLevels", "<id of your hierarchylevel>");
    ?>
    
       Dissociate a hierarchylevel from a column 
    curl https://api.cumul.io/0.1.0/column  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "dissociate",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "id": "<your column id>",
      "resource": {
      "role": "HierarchyLevels",
      "id": "<id of your hierarchylevel>"
    }
    }
    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.

    Country

    Countries simply have a name and an id where the id is the two-letter country code (ISO) in capitals. By default, all countries are listed in the Cumul.io platform. The only use for countries is to provide information on where your users are located to the platform which can be done by associating a country to the user or to the organization. Since countries are managed by Cumul.io, you can not create, delete or update them.

    Properties

    Parameter
    Description
    id
    uuid
    Unique key of the country (automatically assigned)
    name
    string
    Name of the country

    Actions

    Get
    List
    Associate
    Dissociate

    Action: Get & List

       Get a list of all countries 
    JSONObject data = client.get("country", 
      ImmutableMap.of(
    
      ));
    
    
       Get a list of all countries 
    dynamic query = new ExpandoObject();
    
    dynamic data = client.get("country",     query);
    
    
       Get a list of all countries 
    client.get('country', {})
      .then(function(data) {
        console.log('Success!', data);
      });
    
       Get a list of all countries 
    <?php
    $user = $client->get('country', 
      array (
    
      ));
    
    ?>
    
       Get a list of all countries 
    curl https://api.cumul.io/0.1.0/country  -H "Content-Type: application/json" -d @- << EOF
    {
      "action": "get",
      "key": "$CUMULIO_API_KEY",
      "token": "$CUMULIO_API_TOKEN",
      "version": "0.1.0",
      "find": {}
    }
    EOF
    
    
    Get
    can be executed by:
    Anonymous
    Logged-in User
    List
    can be executed by:
    Anonymous
    Logged-in User

    Any user can retrieve countries.

    Associations

    %3 <!-- User --> User User <!-- Country --> Country Country <!-- User->Country --> User->Country <!-- Organization --> Organization Organization <!-- Organization->Country --> Organization->Country

    Associate: Organization

       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
    
    Organization
    Country
    Associate
    requires:
    Organization Owner
    and
    Logged-in User

    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: User

       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
    
    User
    Country
    Associate
    requires:
    Logged-in User
    and
    User Owner

    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.

    Dashboard

    Dashboards can also be created, retrieved and updated programmatically or can be associated programmatically. The dashboard definition itself is configured via a json object in the contents property. This json object defines per view modus which visualization elements that are contained within the dashboard and what position and data connections each of them have. It is important to notice that the structure of this json evolves as we add new visualization types or adapt existing ones. That is why the json starts by declaring the version of the dashboard config. This makes sure that we are backward compatible with dashboard configurations that are created according to an older structure. Although it is possible, typically users do not create a dashboard from scratch. If you want to learn more about this structure, we advice to make a dashboard via the UI and retrieve it via the API to see what it looks like. A common use case is to create dashboards via the editor and add a logo or change colors programmatically.

    Properties

    Parameter
    Description
    id
    uuid
    Unique key of the dashboard (automatically assigned)
    contents
    object
    Json object that describes the structure of the dashboard. Important to notice is that these objects have versions. In case you adapt or create a dashboard via the API, it is important to set this version number.
    type
    string
    Type of the securable, either dataset or dashboard
    subtype
    string
    (Read-only) Creation type of the securable. Defaults to api
    name
    localized
    Title of the dataset or dashboard, shown in the dataset or dashboard header
    subtitle
    localized
    Secondary title of the dashboard, shown in the dashboard header
    description
    localized
    Long-form description of the dataset or dashboard, shown in the dataset or dashboard listings
    css
    string
    CSS code that overrides styling in the dashboard. Example: .pivottable-value { font-size: 18px; }. Defaults to null.
    modified_at
    datetime
    (Read-only) Last modification date of the dataset or dashboard.

    Actions

    Create
    Get
    List
    Delete
    Update
    Associate
    Dissociate

    Action: Create

       Dashboards are securables and are therefore created using the 'securable' resource using the type 'dashboard'. When a Dashboard is created it is automatically linked to the user that created it 
    JSONObject securable = client.create("securable",
    
      ImmutableMap.of(
        "type" , "dashboard",
        "contents" , "{..dashboard contents..}",
        "name" , ImmutableMap.of(
          "en" , "My new Dashboard"
        )
      ));
    System.out.println("Success! %s%n", securable);
    
       Dashboards are securables and are therefore created using the 'securable' resource using the type 'dashboard'. When a Dashboard is created it is automatically linked to the user that created it 
    dynamic properties = new ExpandoObject();
    properties.type = "dashboard";
    properties.contents = "{..dashboard contents..}";
    properties.name = new {
          en = "My new Dashboard"
        };
    
    dynamic securable = client.create("securable",    properties);
    Console.WriteLine("Success!", securable);
    
       Dashboards are securables and are therefore created using the 'securable' resource using the type 'dashboard'. When a Dashboard is created it is automatically linked to the user that created it 
    client.create('securable',
      {
        type: 'dashboard',
        contents: '{..dashboard contents..}',
        name: {
            en: 'My new Dashboard'
        }
    }
    
    )
      .then(function(securable) {
        console.log('Success!', securable);
      });
    
       Dashboards are securables and are therefore created using the 'securable' resource using the type 'dashboard'. When a Dashboard is created it is automatically linked to the user that created it 
    <?php
    $securable = $client->create('securable',
    
      array (
        'type' => 'dashboard',
        'contents' => '{..dashboard contents..}',
        'name' => array (
          'en' => 'My new Dashboard'
        )
      )
    
    );
    print("Success! { $securable }");
    ?>
    
       Dashboards are securables and are therefore created using the 'securable' resource using the type 'dashboard'. When a Dashboard is created it is automatically linked to the user that created it 
    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": "dashboard",
      "contents": "{..dashboard contents..}",
      "name": {
        "en": "My new Dashboard"
      }
    }
    }
    EOF
    
    
       A dashboard has a contents property which defines the dashboard structure. This means that it defines all the elements, their positions, the links with data etc for all the views. Below we examplify the standard structure 
    JSONObject securable = client.create("securable",
    
      ImmutableMap.of(
        "type" , "dashboard",
        "contents" , ImmutableMap.of(
          "version" , "0.1.17",
          "syncScreenModes" , true,
          "items" , ImmutableList.of(
    
          ),
          "views" , ImmutableList.of(
    
            ImmutableMap.of(
              "screenModus" , "desktop",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            ),
    
            ImmutableMap.of(
              "screenModus" , "tablet",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            ),
    
            ImmutableMap.of(
              "screenModus" , "mobile",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            )
          ),
          "dashboardTheme" , ImmutableMap.of(
    
          )
        ),
        "name" , ImmutableMap.of(
          "en" , "My new Dashboard"
        )
      ));
    System.out.println("Success! %s%n", securable);
    
       A dashboard has a contents property which defines the dashboard structure. This means that it defines all the elements, their positions, the links with data etc for all the views. Below we examplify the standard structure 
    dynamic properties = new ExpandoObject();
    properties.type = "dashboard";
    properties.contents = new {
          version = "0.1.17",
          syncScreenModes = true,
          items = new List<Object> {
    
          },
          views = new List<Object> {
    
            new {
              screenModus = "desktop",
              gridOptions = "{..grid contents..}",
              filters = new List<Object> {
    
              },
              items = new List<Object> {
    
              }
            },
    
            new {
              screenModus = "tablet",
              gridOptions = "{..grid contents..}",
              filters = new List<Object> {
    
              },
              items = new List<Object> {
    
              }
            },
    
            new {
              screenModus = "mobile",
              gridOptions = "{..grid contents..}",
              filters = new List<Object> {
    
              },
              items = new List<Object> {
    
              }
            }
          },
          dashboardTheme = new {
    
          }
        };
    properties.name = new {
          en = "My new Dashboard"
        };
    
    dynamic securable = client.create("securable",    properties);
    Console.WriteLine("Success!", securable);
    
       A dashboard has a contents property which defines the dashboard structure. This means that it defines all the elements, their positions, the links with data etc for all the views. Below we examplify the standard structure 
    client.create('securable',
      {
        type: 'dashboard',
        contents: {
            version: '0.1.17',
            syncScreenModes: true,
            items: [],
            views: [
                {
                    screenModus: 'desktop',
                    gridOptions: '{..grid contents..}',
                    filters: [],
                    items: []
                },
                {
                    screenModus: 'tablet',
                    gridOptions: '{..grid contents..}',
                    filters: [],
                    items: []
                },
                {
                    screenModus: 'mobile',
                    gridOptions: '{..grid contents..}',
                    filters: [],
                    items: []
                }
            ],
            dashboardTheme: {}
        },
        name: {
            en: 'My new Dashboard'
        }
    }
    
    )
      .then(function(securable) {
        console.log('Success!', securable);
      });
    
       A dashboard has a contents property which defines the dashboard structure. This means that it defines all the elements, their positions, the links with data etc for all the views. Below we examplify the standard structure 
    <?php
    $securable = $client->create('securable',
    
      array (
        'type' => 'dashboard',
        'contents' => array (
          'version' => '0.1.17',
          'syncScreenModes' => true,
          'items' => array (
    
          ),
          'views' => array (
    
            array (
              'screenModus' => 'desktop',
              'gridOptions' => '{..grid contents..}',
              'filters' => array (
    
              ),
              'items' => array (
    
              )
            ),
    
            array (
              'screenModus' => 'tablet',
              'gridOptions' => '{..grid contents..}',
              'filters' => array (
    
              ),
              'items' => array (
    
              )
            ),
    
            array (
              'screenModus' => 'mobile',
              'gridOptions' => '{..grid contents..}',
              'filters' => array (
    
              ),
              'items' => array (
    
              )
            )
          ),
          'dashboardTheme' => array (
    
          )
        ),
        'name' => array (
          'en' => 'My new Dashboard'
        )
      )
    
    );
    print("Success! { $securable }");
    ?>
    
       A dashboard has a contents property which defines the dashboard structure. This means that it defines all the elements, their positions, the links with data etc for all the views. Below we examplify the standard structure 
    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": "dashboard",
      "contents": {
        "version": "0.1.17",
        "syncScreenModes": true,
        "items": [],
        "views": [
          {
            "screenModus": "desktop",
            "gridOptions": "{..grid contents..}",
            "filters": [],
            "items": []
          },
          {
            "screenModus": "tablet",
            "gridOptions": "{..grid contents..}",
            "filters": [],
            "items": []
          },
          {
            "screenModus": "mobile",
            "gridOptions": "{..grid contents..}",
            "filters": [],
            "items": []
          }
        ],
        "dashboardTheme": {}
      },
      "name": {
        "en": "My new Dashboard"
      }
    }
    }
    EOF
    
    
       A dashboard created with the default values (the table and mobile gridOptions are similar) 
    JSONObject securable = client.create("securable",
    
      ImmutableMap.of(
        "type" , "dashboard",
        "contents" , ImmutableMap.of(
          "name" , ImmutableMap.of(
    
          ),
          "subtitle" , ImmutableMap.of(
    
          ),
          "description" , ImmutableMap.of(
    
          ),
          "contents" , ImmutableMap.of(
            "version" , "0.1.17",
            "syncScreenModes" , true,
            "views" , ImmutableList.of(
    
              ImmutableMap.of(
                "screenModus" , "desktop",
                "gridOptions" , ImmutableMap.of(
                  "showTitle" , true,
                  "showSubtitle" , false,
                  "share" , ImmutableMap.of(
                    "buttons" , true,
                    "poweredBy" , true,
                    "shareButtons" , ImmutableList.of(
                      "linkedin",
                      "facebook",
                      "twitter",
                      "email"
                    )
                  ),
                  "theme" , ImmutableMap.of(
                    "id" , "default"
                  ),
                  "width" , "auto",
                  "minRows" , "1",
                  "maxRows" , "2000",
                  "pushing" , true,
                  "swapping" , true,
                  "floating" , true,
                  "sparse" , true,
                  "columns" , "48",
                  "colWidth" , "auto",
                  "rowHeight" , "16",
                  "margins" , ImmutableList.of(
                    "10",
                    "10"
                  ),
                  "defaultSizeX" , "12",
                  "defaultSizeY" , "6",
                  "mobileModeEnabled" , false,
                  "mobileBreakPoint" , "100"
                ),
                "filters" , ImmutableList.of(
    
                ),
                "items" , ImmutableList.of(
    
                )
              ),
    
              ImmutableMap.of(
                "screenModus" , "tablet",
                "gridOptions" , "...",
                "filters" , ImmutableList.of(
    
                ),
                "items" , ImmutableList.of(
    
                )
              ),
    
              ImmutableMap.of(
                "screenModus" , "mobile",
                "gridOptions" , "...",
                "filters" , ImmutableList.of(
    
                ),
                "items" , ImmutableList.of(
    
                )
              )
            )
          )
        ),
        "name" , ImmutableMap.of(
          "en" , "My new Dashboard"
        )
      ));
    System.out.println("Success! %s%n", securable);
    
       A dashboard created with the default values (the table and mobile gridOptions are similar) 
    dynamic properties = new ExpandoObject();
    properties.type = "dashboard";
    properties.contents = new {
          name = new {
    
          },
          subtitle = new {
    
          },
          description = new {
    
          },
          contents = new {
            version = "0.1.17",
            syncScreenModes = true,
            views = new List<Object> {
    
              new {
                screenModus = "desktop",
                gridOptions = new {
                  showTitle = true,
                  showSubtitle = false,
                  share = new {
                    buttons = true,
                    poweredBy = true,
                    shareButtons = new List<Object> {
                      "linkedin",
                      "facebook",
                      "twitter",
                      "email"
                    }
                  },
                  theme = new {
                    id = "default"
                  },
                  width = "auto",
                  minRows = "1",
                  maxRows = "2000",
                  pushing = true,
                  swapping = true,
                  floating = true,
                  sparse = true,
                  columns = "48",
                  colWidth = "auto",
                  rowHeight = "16",
                  margins = new List<Object> {
                    "10",
                    "10"
                  },
                  defaultSizeX = "12",
                  defaultSizeY = "6",
                  mobileModeEnabled = false,
                  mobileBreakPoint = "100"
                },
                filters = new List<Object> {
    
                },
                items = new List<Object> {
    
                }
              },
    
              new {
                screenModus = "tablet",
                gridOptions = "...",
                filters = new List<Object> {
    
                },
                items = new List<Object> {
    
                }
              },
    
              new {
                screenModus = "mobile",
                gridOptions = "...",
                filters = new List<Object> {
    
                },
                items = new List<Object> {
    
                }
              }
            }
          }
        };
    properties.name = new {
          en = "My new Dashboard"
        };
    
    dynamic securable = client.create("securable",    properties);
    Console.WriteLine("Success!", securable);
    
       A dashboard created with the default values (the table and mobile gridOptions are similar) 
    client.create('securable',
      {
        type: 'dashboard',
        contents: {
            name: {},
            subtitle: {},
            description: {},
            contents: {
                version: '0.1.17',
                syncScreenModes: true,
                views: [
                    {
                        screenModus: 'desktop',
                        gridOptions: {
                            showTitle: true,
                            showSubtitle: false,
                            share: {
                                buttons: true,
                                poweredBy: true,
                                shareButtons: [
                                    'linkedin',
                                    'facebook',
                                    'twitter',
                                    'email'
                                ]
                            },
                            theme: {
                                id: 'default'
                            },
                            width: 'auto',
                            minRows: 1,
                            maxRows: 2000,
                            pushing: true,
                            swapping: true,
                            floating: true,
                            sparse: true,
                            columns: 48,
                            colWidth: 'auto',
                            rowHeight: 16,
                            margins: [
                                10,
                                10
                            ],
                            defaultSizeX: 12,
                            defaultSizeY: 6,
                            mobileModeEnabled: false,
                            mobileBreakPoint: 100
                        },
                        filters: [],
                        items: []
                    },
                    {
                        screenModus: 'tablet',
                        gridOptions: '...',
                        filters: [],
                        items: []
                    },
                    {
                        screenModus: 'mobile',
                        gridOptions: '...',
                        filters: [],
                        items: []
                    }
                ]
            }
        },
        name: {
            en: 'My new Dashboard'
        }
    }
    
    )
      .then(function(securable) {
        console.log('Success!', securable);
      });
    
       A dashboard created with the default values (the table and mobile gridOptions are similar) 
    <?php
    $securable = $client->create('securable',
    
      array (
        'type' => 'dashboard',
        'contents' => array (
          'name' => array (
    
          ),
          'subtitle' => array (
    
          ),
          'description' => array (
    
          ),
          'contents' => array (
            'version' => '0.1.17',
            'syncScreenModes' => true,
            'views' => array (
    
              array (
                'screenModus' => 'desktop',
                'gridOptions' => array (
                  'showTitle' => true,
                  'showSubtitle' => false,
                  'share' => array (
                    'buttons' => true,
                    'poweredBy' => true,
                    'shareButtons' => array (
                      'linkedin',
                      'facebook',
                      'twitter',
                      'email'
                    )
                  ),
                  'theme' => array (
                    'id' => 'default'
                  ),
                  'width' => 'auto',
                  'minRows' => '1',
                  'maxRows' => '2000',
                  'pushing' => true,
                  'swapping' => true,
                  'floating' => true,
                  'sparse' => true,
                  'columns' => '48',
                  'colWidth' => 'auto',
                  'rowHeight' => '16',
                  'margins' => array (
                    '10',
                    '10'
                  ),
                  'defaultSizeX' => '12',
                  'defaultSizeY' => '6',
                  'mobileModeEnabled' => false,
                  'mobileBreakPoint' => '100'
                ),
                'filters' => array (
    
                ),
                'items' => array (
    
                )
              ),
    
              array (
                'screenModus' => 'tablet',
                'gridOptions' => '...',
                'filters' => array (
    
                ),
                'items' => array (
    
                )
              ),
    
              array (
                'screenModus' => 'mobile',
                'gridOptions' => '...',
                'filters' => array (
    
                ),
                'items' => array (
    
                )
              )
            )
          )
        ),
        'name' => array (
          'en' => 'My new Dashboard'
        )
      )
    
    );
    print("Success! { $securable }");
    ?>
    
       A dashboard created with the default values (the table and mobile gridOptions are similar) 
    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": "dashboard",
      "contents": {
        "name": {},
        "subtitle": {},
        "description": {},
        "contents": {
          "version": "0.1.17",
          "syncScreenModes": true,
          "views": [
            {
              "screenModus": "desktop",
              "gridOptions": {
                "showTitle": true,
                "showSubtitle": false,
                "share": {
                  "buttons": true,
                  "poweredBy": true,
                  "shareButtons": [
                    "linkedin",
                    "facebook",
                    "twitter",
                    "email"
                  ]
                },
                "theme": {
                  "id": "default"
                },
                "width": "auto",
                "minRows": 1,
                "maxRows": 2000,
                "pushing": true,
                "swapping": true,
                "floating": true,
                "sparse": true,
                "columns": 48,
                "colWidth": "auto",
                "rowHeight": 16,
                "margins": [
                  10,
                  10
                ],
                "defaultSizeX": 12,
                "defaultSizeY": 6,
                "mobileModeEnabled": false,
                "mobileBreakPoint": 100
              },
              "filters": [],
              "items": []
            },
            {
              "screenModus": "tablet",
              "gridOptions": "...",
              "filters": [],
              "items": []
            },
            {
              "screenModus": "mobile",
              "gridOptions": "...",
              "filters": [],
              "items": []
            }
          ]
        }
      },
      "name": {
        "en": "My new Dashboard"
      }
    }
    }
    EOF
    
    
       An example with a partial dashboard definition where items contains a barchart 
    JSONObject securable = client.create("securable",
    
      ImmutableMap.of(
        "type" , "dashboard",
        "contents" , ImmutableMap.of(
          "version" , "0.1.17",
          "syncScreenModes" , true,
          "items" , ImmutableList.of(
    
            ImmutableMap.of(
              "id" , "49a23940-0dcb-4df3-9df5-2f0a14756bfa",
              "type" , "bar-chart",
              "position" , ImmutableMap.of(
                "sizeX" , "24",
                "sizeY" , "20",
                "row" , "0",
                "col" , "9"
              ),
              "title" , ImmutableMap.of(
                "en" , "Bar chart"
              ),
              "options" , ImmutableMap.of(
                "startWithSubType" , "bar"
              ),
              "content" , ImmutableMap.of(
    
              ),
              "slots" , ImmutableList.of(
    
                ImmutableMap.of(
                  "name" , "y-axis",
                  "description" , "Category",
                  "content" , ImmutableList.of(
    
                    ImmutableMap.of(
                      "column" , "{{column_id}}",
                      "set" , "{{dataset_id}}",
                      "label" , ImmutableMap.of(
                        "en" , "Acquisition"
                      ),
                      "type" , "hierarchy",
                      "color" , "null",
                      "lowestLevel" , "0",
                      "level" , "null"
                    )
                  ),
                  "required" , false,
                  "multiple" , false,
                  "accept" , ImmutableList.of(
                    "hierarchy",
                    "numeric",
                    "datetime"
                  )
                ),
    
                ImmutableMap.of(
                  "name" , "measure",
                  "description" , "Measure",
                  "content" , ImmutableList.of(
    
                  ),
                  "multiple" , true,
                  "required" , false,
                  "accept" , ImmutableList.of(
                    "hierarchy",
                    "numeric",
                    "datetime"
                  )
                ),
    
                ImmutableMap.of(
                  "name" , "legend",
                  "description" , "Legend",
                  "content" , ImmutableList.of(
    
                  ),
                  "multiple" , false,
                  "required" , false,
                  "accept" , ImmutableList.of(
                    "hierarchy",
                    "numeric",
                    "datetime"
                  )
                )
              )
            )
          ),
          "views" , ImmutableList.of(
    
            ImmutableMap.of(
              "screenModus" , "desktop",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            ),
    
            ImmutableMap.of(
              "screenModus" , "tablet",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            ),
    
            ImmutableMap.of(
              "screenModus" , "mobile",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            )
          ),
          "dashboardTheme" , ImmutableMap.of(
    
          )
        ),
        "name" , ImmutableMap.of(
          "en" , "My new Dashboard"
        )
      ));
    System.out.println("Success! %s%n", securable);
    
       An example with a partial dashboard definition where items contains a barchart 
    dynamic properties = new ExpandoObject();
    properties.type = "dashboard";
    properties.contents = new {
          version = "0.1.17",
          syncScreenModes = true,
          items = new List<Object> {
    
            new {
              id = "49a23940-0dcb-4df3-9df5-2f0a14756bfa",
              type = "bar-chart",
              position = new {
                sizeX = "24",
                sizeY = "20",
                row = "0",
                col = "9"
              },
              title = new {
                en = "Bar chart"
              },
              options = new {
                startWithSubType = "bar"
              },
              content = new {
    
              },
              slots = new List<Object> {
    
                new {
                  name = "y-axis",
                  description = "Category",
                  content = new List<Object> {
    
                    new {
                      column = "{{column_id}}",
                      set = "{{dataset_id}}",
                      label = new {
                        en = "Acquisition"
                      },
                      type = "hierarchy",
                      color = "null",
                      lowestLevel = "0",
                      level = "null"
                    }
                  },
                  required = false,
                  multiple = false,
                  accept = new List<Object> {
                    "hierarchy",
                    "numeric",
                    "datetime"
                  }
                },
    
                new {
                  name = "measure",
                  description = "Measure",
                  content = new List<Object> {
    
                  },
                  multiple = true,
                  required = false,
                  accept = new List<Object> {
                    "hierarchy",
                    "numeric",
                    "datetime"
                  }
                },
    
                new {
                  name = "legend",
                  description = "Legend",
                  content = new List<Object> {
    
                  },
                  multiple = false,
                  required = false,
                  accept = new List<Object> {
                    "hierarchy",
                    "numeric",
                    "datetime"
                  }
                }
              }
            }
          },
          views = new List<Object> {
    
            new {
              screenModus = "desktop",
              gridOptions = "{..grid contents..}",
              filters = new List<Object> {
    
              },
              items = new List<Object> {
    
              }
            },
    
            new {
              screenModus = "tablet",
              gridOptions = "{..grid contents..}",
              filters = new List<Object> {
    
              },
              items = new List<Object> {
    
              }
            },
    
            new {
              screenModus = "mobile",
              gridOptions = "{..grid contents..}",
              filters = new List<Object> {
    
              },
              items = new List<Object> {
    
              }
            }
          },
          dashboardTheme = new {
    
          }
        };
    properties.name = new {
          en = "My new Dashboard"
        };
    
    dynamic securable = client.create("securable",    properties);
    Console.WriteLine("Success!", securable);
    
       An example with a partial dashboard definition where items contains a barchart 
    client.create('securable',
      {
        type: 'dashboard',
        contents: {
            version: '0.1.17',
            syncScreenModes: true,
            items: [
                {
                    id: '49a23940-0dcb-4df3-9df5-2f0a14756bfa',
                    type: 'bar-chart',
                    position: {
                        sizeX: 24,
                        sizeY: 20,
                        row: 0,
                        col: 9
                    },
                    title: {
                        en: 'Bar chart'
                    },
                    options: {
                        startWithSubType: 'bar'
                    },
                    content: {},
                    slots: [
                        {
                            name: 'y-axis',
                            description: 'Category',
                            content: [
                                {
                                    column: '{{column_id}}',
                                    set: '{{dataset_id}}',
                                    label: {
                                        en: 'Acquisition'
                                    },
                                    type: 'hierarchy',
                                    color: null,
                                    lowestLevel: 0,
                                    level: null
                                }
                            ],
                            required: false,
                            multiple: false,
                            accept: [
                                'hierarchy',
                                'numeric',
                                'datetime'
                            ]
                        },
                        {
                            name: 'measure',
                            description: 'Measure',
                            content: [],
                            multiple: true,
                            required: false,
                            accept: [
                                'hierarchy',
                                'numeric',
                                'datetime'
                            ]
                        },
                        {
                            name: 'legend',
                            description: 'Legend',
                            content: [],
                            multiple: false,
                            required: false,
                            accept: [
                                'hierarchy',
                                'numeric',
                                'datetime'
                            ]
                        }
                    ]
                }
            ],
            views: [
                {
                    screenModus: 'desktop',
                    gridOptions: '{..grid contents..}',
                    filters: [],
                    items: []
                },
                {
                    screenModus: 'tablet',
                    gridOptions: '{..grid contents..}',
                    filters: [],
                    items: []
                },
                {
                    screenModus: 'mobile',
                    gridOptions: '{..grid contents..}',
                    filters: [],
                    items: []
                }
            ],
            dashboardTheme: {}
        },
        name: {
            en: 'My new Dashboard'
        }
    }
    
    )
      .then(function(securable) {
        console.log('Success!', securable);
      });
    
       An example with a partial dashboard definition where items contains a barchart 
    <?php
    $securable = $client->create('securable',
    
      array (
        'type' => 'dashboard',
        'contents' => array (
          'version' => '0.1.17',
          'syncScreenModes' => true,
          'items' => array (
    
            array (
              'id' => '49a23940-0dcb-4df3-9df5-2f0a14756bfa',
              'type' => 'bar-chart',
              'position' => array (
                'sizeX' => '24',
                'sizeY' => '20',
                'row' => '0',
                'col' => '9'
              ),
              'title' => array (
                'en' => 'Bar chart'
              ),
              'options' => array (
                'startWithSubType' => 'bar'
              ),
              'content' => array (
    
              ),
              'slots' => array (
    
                array (
                  'name' => 'y-axis',
                  'description' => 'Category',
                  'content' => array (
    
                    array (
                      'column' => '{{column_id}}',
                      'set' => '{{dataset_id}}',
                      'label' => array (
                        'en' => 'Acquisition'
                      ),
                      'type' => 'hierarchy',
                      'color' => 'null',
                      'lowestLevel' => '0',
                      'level' => 'null'
                    )
                  ),
                  'required' => false,
                  'multiple' => false,
                  'accept' => array (
                    'hierarchy',
                    'numeric',
                    'datetime'
                  )
                ),
    
                array (
                  'name' => 'measure',
                  'description' => 'Measure',
                  'content' => array (
    
                  ),
                  'multiple' => true,
                  'required' => false,
                  'accept' => array (
                    'hierarchy',
                    'numeric',
                    'datetime'
                  )
                ),
    
                array (
                  'name' => 'legend',
                  'description' => 'Legend',
                  'content' => array (
    
                  ),
                  'multiple' => false,
                  'required' => false,
                  'accept' => array (
                    'hierarchy',
                    'numeric',
                    'datetime'
                  )
                )
              )
            )
          ),
          'views' => array (
    
            array (
              'screenModus' => 'desktop',
              'gridOptions' => '{..grid contents..}',
              'filters' => array (
    
              ),
              'items' => array (
    
              )
            ),
    
            array (
              'screenModus' => 'tablet',
              'gridOptions' => '{..grid contents..}',
              'filters' => array (
    
              ),
              'items' => array (
    
              )
            ),
    
            array (
              'screenModus' => 'mobile',
              'gridOptions' => '{..grid contents..}',
              'filters' => array (
    
              ),
              'items' => array (
    
              )
            )
          ),
          'dashboardTheme' => array (
    
          )
        ),
        'name' => array (
          'en' => 'My new Dashboard'
        )
      )
    
    );
    print("Success! { $securable }");
    ?>
    
       An example with a partial dashboard definition where items contains a barchart 
    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": "dashboard",
      "contents": {
        "version": "0.1.17",
        "syncScreenModes": true,
        "items": [
          {
            "id": "49a23940-0dcb-4df3-9df5-2f0a14756bfa",
            "type": "bar-chart",
            "position": {
              "sizeX": 24,
              "sizeY": 20,
              "row": 0,
              "col": 9
            },
            "title": {
              "en": "Bar chart"
            },
            "options": {
              "startWithSubType": "bar"
            },
            "content": {},
            "slots": [
              {
                "name": "y-axis",
                "description": "Category",
                "content": [
                  {
                    "column": "{{column_id}}",
                    "set": "{{dataset_id}}",
                    "label": {
                      "en": "Acquisition"
                    },
                    "type": "hierarchy",
                    "color": null,
                    "lowestLevel": 0,
                    "level": null
                  }
                ],
                "required": false,
                "multiple": false,
                "accept": [
                  "hierarchy",
                  "numeric",
                  "datetime"
                ]
              },
              {
                "name": "measure",
                "description": "Measure",
                "content": [],
                "multiple": true,
                "required": false,
                "accept": [
                  "hierarchy",
                  "numeric",
                  "datetime"
                ]
              },
              {
                "name": "legend",
                "description": "Legend",
                "content": [],
                "multiple": false,
                "required": false,
                "accept": [
                  "hierarchy",
                  "numeric",
                  "datetime"
                ]
              }
            ]
          }
        ],
        "views": [
          {
            "screenModus": "desktop",
            "gridOptions": "{..grid contents..}",
            "filters": [],
            "items": []
          },
          {
            "screenModus": "tablet",
            "gridOptions": "{..grid contents..}",
            "filters": [],
            "items": []
          },
          {
            "screenModus": "mobile",
            "gridOptions": "{..grid contents..}",
            "filters": [],
            "items": []
          }
        ],
        "dashboardTheme": {}
      },
      "name": {
        "en": "My new Dashboard"
      }
    }
    }
    EOF
    
    
       An example of a dashboard theme which can be useful if you want to programmatically change themes for specific users. 
    JSONObject securable = client.create("securable",
    
      ImmutableMap.of(
        "type" , "dashboard",
        "contents" , ImmutableMap.of(
          "version" , "0.1.17",
          "syncScreenModes" , true,
          "items" , ImmutableList.of(
    
          ),
          "views" , ImmutableList.of(
    
            ImmutableMap.of(
              "screenModus" , "desktop",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            ),
    
            ImmutableMap.of(
              "screenModus" , "tablet",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            ),
    
            ImmutableMap.of(
              "screenModus" , "mobile",
              "gridOptions" , "{..grid contents..}",
              "filters" , ImmutableList.of(
    
              ),
              "items" , ImmutableList.of(
    
              )
            )
          ),
          "dashboardTheme" , ImmutableMap.of(
            "type" , "platform",
            "name" , "Default (light)",
            "background" , "#F2F2F2",
            "itemsBackground" , "#ffffff",
            "boxShadow" , ImmutableMap.of(
              "size" , "none",
              "color" , "rgb(0,0,0)"
            ),
            "title" , ImmutableMap.of(
              "itemTitleAlignment" , "center",
              "itemTitleBold" , false,
              "itemTitleItalic" , false,
              "text-decoration" , false,
              "itemTitleBorder" , true
            ),
            "editModeBackground" , "#ececec",
            "borders" , ImmutableMap.of(
              "border-color" , "rgba(0,0,0,.1)",
              "border-radius" , "3px",
              "border-style" , "solid",
              "border-top-width" , "1px",
              "border-right-width" , "1px",
              "border-bottom-width" , "1px",
              "border-left-width" , "1px"
            ),
            "margins" , ImmutableList.of(
              "10",
              "10"
            ),
            "mainColor" , "#009dff",
            "colors" , ImmutableList.of(
              "#0E89E0",
              "#52B6F0",
              "#8FD0F1",
              "#BDDCF9",
              "#F45000",
              "#FF8E3B",
              "#FFB069",
              "#FFCFA1",
              "#15BF49",
              "#60D863",
              "#95E88C",
              "#C1F3B7",
              "#685AC2",
              "#958FD3",
              "#B4B6E4",
              "#D7D7EF",
              "#636363",
              "#969696",
              "#BDBDBD",
              "#D9D9D9"
            ),
            "font"