API access to Pivot

You can use the API to create, modify, and delete resources in Pivot.

To enable the API you need to add to the config

enableApiEndpoint: true

You can then go the API page to create a token.

api toke

Once the token is created you can need to supply it with x-imply-api-token header when you make requests to /api/v1/<resource-name>.

The resource-name can be one of:

Adding ?pretty to the URL makes the return values in pretty printed JSON.

Endpoints

Read

// read all data cubes
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/data-cubes

// read all dashboards
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/dashboards

// read all users
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/users?pretty

// read all user-auths
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/user-auths

// read all roles
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/roles

// read all connections
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/connections


// read a dataCube by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/data-cubes/<dataCubeName>

// read a dashboard by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/dashboards/<dashboardName>

// read a user by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/users/<userName>

// read a user-auth by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/user-auths/<userAuthName>

// read a role by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/roles/<roleName>

// read a connection by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/connections/<connectionName>

Example:

curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/data-cubes/6027_9

Results in:

{"dataCube":{"name":"6027_9","title":"wiki","connectionName":"6027","source":"wikipedia","dimensions":[{"name":"articleName","title":"Article Name","formula":"$articleName","type":"STRING"}],"measures":[{"name":"count","title":"Count","formula":"$main.sum($count)"}],"specialTimeDimension":"!NONE","enforceTimeFilter":false}}

Create

// create a dataCube
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "dataCube": {<resource object>}
}
' localhost:9095/api/v1/data-cubes

// create a dashboard
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "dashboard": {<resource object>}
}
' localhost:9095/api/v1/dashboards

// create a user
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "user": {<resource object>}
}
' localhost:9095/api/v1/users

// create a user-auth
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "userAuth": {<resource object>}
}
' localhost:9095/api/v1/user-auths

// create a role
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "role": {<resource object>}
}
' localhost:9095/api/v1/roles

// create a connection
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "connection": {<resource object>}
}
' localhost:9095/api/v1/connections

Example 1:

input:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "dataCube": {
    "name": "zzz_hello",
    "title": "zzz",
    "connectionName": "6027",
    "source": "wikipedia",
    "dimensions": [
      {
        "name": "articleName"
      }
    ],
    "measures": [
      {
        "name": "count",
        "formula": "$main.sum($count)"
      }
    ]
  }
}
' localhost:9095/api/v1/data-cubes

Results in:

{"status":"ok","message":"Created successfully","dataCube":{"name":"zzz_hello","title":"zzz","connectionName":"6027","source":"wikipedia","dimensions":[{"name":"articleName","title":"Article Name","formula":"$articleName","type":"STRING"}],"measures":[{"name":"count","title":"Count","formula":"$main.sum($count)"}],"specialTimeDimension":"!NONE","enforceTimeFilter":false}}

Example 2:

You could add "sendWelcomeEmail": true to the body when creating a new user.

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:ea750788-9ee5-4498-b2eb-ea25d7a62af5" --data '
{
  "user": {
    "name": "someuser@imply.io",
    "colorMode": "dark-color-mode",
    "email": "someuser@imply.io",
    "firstName": "some",
    "lastName": "user",
    "status": "new",
    "roles": [
      "sweet-role"
    ]
  },
  "sendWelcomeEmail": true
}' localhost:9095/api/v1/users?pretty

Results in:

{
  "sendEmailStatus": "ok",
  "status": "ok",
  "message": "Created successfully",
  "user": {
    "name": "someuser@imply.io",
    "colorMode": "dark-color-mode",
    "email": "someuser@imply.io",
    "firstName": "some",
    "lastName": "user",
    "status": "new",
    "roles": [
      "sweet-role"
    ]
  }
}

Update

// update a dataCube by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "dataCube": {<resource object>}
}
' localhost:9095/api/v1/data-cubes/<dataCubeName>

// update a dashboard by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "dashboard": {<resource object>}
}
' localhost:9095/api/v1/dashboards/<dashboardName>

// update a user by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "user": {<resource object>}
}
' localhost:9095/api/v1/users/<userName>

// update a user-auth by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "userAuth": {<resource object>}
}
' localhost:9095/api/v1/user-auths/<userAuthName>

// update a role by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "role": {<resource object>}
}
' localhost:9095/api/v1/roles/<roleName>

// update a connection by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "connection": {<resource object>}
}
' localhost:9095/api/v1/connections/<connectionName>

Example:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "dataCube": {
    "name": "zzz_hello",
    "title": "ThisNewTitle",
    "connectionName": "6027",
    "source": "wikipedia",
    "dimensions": [
      {
        "name": "articleName"
      }
    ],
    "measures": [
      {
        "name": "count",
        "formula": "$main.sum($count)"
      }
    ]
  }
}
' localhost:9095/api/v1/data-cubes/zzz_hello

Results in:

{"status":"ok","message":"Updated successfully","dataCube":{"name":"zzz_hello","title":"ThisNewTitle","connectionName":"6027","source":"wikipedia","dimensions":[{"name":"articleName","title":"Article Name","formula":"$articleName","type":"STRING"}],"measures":[{"name":"count","title":"Count","formula":"$main.sum($count)"}],"specialTimeDimension":"!NONE","enforceTimeFilter":false}}

Delete

// delete a dataCube by name, the name is required
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/data-cubes/<dataCubeName>

// delete a dashboard by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/dashboards/<dashboardName>

// delete a user by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/users/<userName>

// delete a user -auth by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/user-auths/<userAuthName>


// delete a role by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/roles/<roleName>

// delete a connection by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/connections/<connectionName>

Example:

curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/data-cubes/zzz_hello

Results in:

{"status":"ok","message":"Deleted successfully"}
Overview

Tutorial

Deploy

Manage Data

Query Data

Visualize

Configure

Special UI Features

Misc