Pivot API

The Pivot API is available only for Imply Private (i.e., self-hosted) or for Imply Cloud when using direct-access mode.

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

To enable the API you need to add the following to the Pivot configuration file:

enableApiEndpoint: true

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

api toke

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)
alerts - The alerts
reports - The scheduled reports

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 all alerts
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/alerts

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

// 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>

// read an alert by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/alerts/<alertName>

// read a report by name
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/reports/<reportName>

Example 1: Read a data cube by name

Input:

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

Result:

{
  "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
  }
}

Example 2: Read all alerts

Input:

curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/alerts

Result:

{
  "alerts": [
    {
      "name": "8797",
      "owner": "user@company.com",
      "title": "An awesome alert",
      "dataCube": "078b_16",
      "checkFrequency": "PT1M",
      "type": "overall",
      "timeFrame": "P1D",
      "filter": {},
      "splits": [],
      "conditions": [
        {
          "type": "percent-delta",
          "measure": "count",
          "condition": "greaterThan",
          "value": "1"
        }
      ],
      "recipients": {
        "access": "single",
        "users": ["user@company.com"]
      },
      "admins": {
        "access": "single",
        "users": ["user@company.com"]
      },
      "webhooks": [],
      "compare": {
        "type": "relative",
        "duration": "P1D"
      },
      "sendEmailToRecipients": false
    }
  ]
}

Example 3: Read all reports

Input:

curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/reports

Result:

{
  "reports": [
    {
      "name": "704b",
      "owner": "user@company.com",
      "creationDate": "2020-01-27T17:33:32.133Z",
      "title": "New Report",
      "delivery": {
        "frequency": "P1D",
        "day": 1,
        "time": 8,
        "dayType": "of-week",
        "frequencyType": "custom"
      },
      "essence": {
        "dataCube": "078b_1",
        "filter": {},
        "splits": [],
        "selectedMeasures": ["count"],
        "pinnedDimensions": [],
        "timezone": "Etc/UTC"
      },
      "admins": {
        "access": "specific",
        "users": ["user@company.com"]
      },
      "externalEmails": []
    }
  ]
}

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

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

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

Example 1: Create a data cube by name

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

Result:

{
  "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: Create a user

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

Input:

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

Result:

{
  "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"]
  }
}

Example 3: Create an alert by name

Input:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "alert": {
    "name": "23456789",
    "owner": "user@company.com",
    "title": "Another super alert",
    "dataCube": "078b_16",
    "checkFrequency": "PT1M",
    "type": "overall",
    "timeFrame": "P1D",
    "filter": {},
    "splits": [],
    "conditions": [
      {
        "type": "percent-delta",
        "measure": "count",
        "condition": "greaterThan",
        "value": "1"
      }
    ],
    "recipients": {
      "access": "single",
      "users": [
        "user@company.com"
      ]
    },
    "admins": {
      "access": "single",
      "users": [
        "user@company.com"
      ]
    },
    "webhooks": [],
    "compare": {
      "type": "relative",
      "duration": "P1D"
    },
    "sendEmailToRecipients": false
  }
}
' localhost:9095/api/v1/alerts

Result:

{
  "status": "ok",
  "message": "Created successfully",
  "alert": {
    "name": "23456789",
    "owner": "user@company.com",
    "title": "Another super alert",
    "dataCube": "078b_16",
    "checkFrequency": "PT1M",
    "type": "overall",
    "timeFrame": "P1D",
    "filter": {},
    "splits": [],
    "conditions": [
      {
        "type": "percent-delta",
        "measure": "count",
        "condition": "greaterThan",
        "value": "1"
      }
    ],
    "recipients": {
      "access": "single",
      "users": ["user@company.com"]
    },
    "admins": {
      "access": "single",
      "users": ["user@company.com"]
    },
    "webhooks": [],
    "compare": {
      "type": "relative",
      "duration": "P1D"
    },
    "sendEmailToRecipients": false
  }
}

Example 4: Create a report by name

Input:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "report": {
    "name": "705b",
    "owner": "user@company.com",
    "creationDate": "2020-01-27T17:33:32.133Z",
    "title": "New Report",
    "delivery": {
      "frequency": "P1D",
      "day": 1,
      "time": 8,
      "dayType": "of-week",
      "frequencyType": "custom"
    },
    "essence": {
      "dataCube": "078b_1",
      "filter": {},
      "splits": [],
      "selectedMeasures": [
        "count"
      ],
      "pinnedDimensions": [],
      "timezone": "Etc/UTC"
    },
    "admins": {
      "access": "specific",
      "users": [
        "user@company.com"
      ]
    },
    "externalEmails": []
  }
}
' localhost:9095/api/v1/reports

Result:

{
  "status": "ok",
  "message": "Created successfully",
  "report": {
    "name": "705b",
    "owner": "user@company.com",
    "creationDate": "2020-01-27T17:33:32.133Z",
    "title": "New Report",
    "delivery": {
      "frequency": "P1D",
      "day": 1,
      "time": 8,
      "dayType": "of-week",
      "frequencyType": "custom"
    },
    "essence": {
      "dataCube": "078b_1",
      "filter": {},
      "splits": [],
      "selectedMeasures": ["count"],
      "pinnedDimensions": [],
      "timezone": "Etc/UTC"
    },
    "admins": {
      "access": "specific",
      "users": ["user@company.com"]
    },
    "externalEmails": []
  }
}

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>

// update an alert by name
curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "alert": {<resource object>}
}
' localhost:9095/api/v1/alerts/<alertName>

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

Example 1: Update a data cube by name

Input:

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

Result:

{
  "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
  }
}

Example 2: Update an alert by name

Input:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "alert": {
    "name": "23456789",
    "owner": "user@company.com",
    "title": "This is a new title for this alert",
    "dataCube": "078b_16",
    "checkFrequency": "PT1M",
    "type": "overall",
    "timeFrame": "P1D",
    "filter": {},
    "splits": [],
    "conditions": [
      {
        "type": "percent-delta",
        "measure": "count",
        "condition": "greaterThan",
        "value": "1"
      }
    ],
    "recipients": {
      "access": "single",
      "users": [
        "user@company.com"
      ]
    },
    "admins": {
      "access": "single",
      "users": [
        "user@company.com"
      ]
    },
    "webhooks": [],
    "compare": {
      "type": "relative",
      "duration": "P1D"
    },
    "sendEmailToRecipients": false
  }
}
' localhost:9095/api/v1/alerts/23456789

Result:

{
  "status": "ok",
  "message": "Updated successfully",
  "alert": {
    "name": "23456789",
    "owner": "user@company.com",
    "title": "This is a new title for this alert",
    "dataCube": "078b_16",
    "checkFrequency": "PT1M",
    "type": "overall",
    "timeFrame": "P1D",
    "filter": {},
    "splits": [],
    "conditions": [
      {
        "type": "percent-delta",
        "measure": "count",
        "condition": "greaterThan",
        "value": "1"
      }
    ],
    "recipients": {
      "access": "single",
      "users": ["user@company.com"]
    },
    "admins": {
      "access": "single",
      "users": ["user@company.com"]
    },
    "webhooks": [],
    "compare": {
      "type": "relative",
      "duration": "P1D"
    },
    "sendEmailToRecipients": false
  }
}

Example 3: Update a report by name

Input:

curl -X POST --header "Content-Type:application/json" --header "x-imply-api-token:<token>" --data '
{
  "report": {
    "name": "705b",
    "owner": "user@company.com",
    "creationDate": "2020-01-27T17:33:32.133Z",
    "title": "Another title again for this report",
    "delivery": {
      "frequency": "P1D",
      "day": 1,
      "time": 8,
      "dayType": "of-week",
      "frequencyType": "custom"
    },
    "essence": {
      "dataCube": "078b_1",
      "filter": {},
      "splits": [],
      "selectedMeasures": [
        "count"
      ],
      "pinnedDimensions": [],
      "timezone": "Etc/UTC"
    },
    "admins": {
      "access": "specific",
      "users": [
        "user@company.com"
      ]
    },
    "externalEmails": []
  }
}
' localhost:9095/api/v1/reports/705b

Result:

{
  "status": "ok",
  "message": "Updated successfully",
  "report": {
    "name": "705b",
    "owner": "user@company.com",
    "creationDate": "2020-01-27T17:33:32.133Z",
    "title": "Another title again for this report",
    "delivery": {
      "frequency": "P1D",
      "day": 1,
      "time": 8,
      "dayType": "of-week",
      "frequencyType": "custom"
    },
    "essence": {
      "dataCube": "078b_1",
      "filter": {},
      "splits": [],
      "selectedMeasures": ["count"],
      "pinnedDimensions": [],
      "timezone": "Etc/UTC"
    },
    "admins": {
      "access": "specific",
      "users": ["user@company.com"]
    },
    "externalEmails": []
  }
}

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>

// delete an alert by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/alerts/<alertName>

// delete a report by name
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/reports/<reportName>

Example:

Input:

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

Result:

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

2021.02

Data cubes

Dashboards

Endpoints

Read

Create

Update

Delete