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 to the API page to create a token.

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

The resource-name can be one of:

• users - The user object describing a user and their roles
• user-auths - The user authorization containing a hashed password
• roles - The roles that a user can belong to
• connections - The connections describing clusters that can be connected to
• data-cubes - The data cubes (and their access permissions)
• dashboards - The dashboards (and their access permissions)

Adding ?pretty to the URL formats the return values as 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" }