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 rolesuser-auths
- The user authorization containing a hashed passwordroles
- The roles that a user can belong toconnections
- The connections describing clusters that can be connected todata-cubes
- The data cubes (and their access permissions)dashboards
- The dashboards (and their access permissions)alerts
- The alertsreports
- The scheduled reportsAdding ?pretty
to the URL formats the return values as pretty printed JSON.
// 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
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
}
}
Example 2: Read all alerts
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/alerts
Results in:
{
"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
curl --header "x-imply-api-token:<token>" localhost:9095/api/v1/reports
Results in:
{
"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 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
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: Create a user
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"]
}
}
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
Results in:
{
"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
Results in:
{
"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 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
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
}
}
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
Results in:
{
"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
Results in:
{
"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 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:
curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/data-cubes/zzz_hello
Results in:
{ "status": "ok", "message": "Deleted successfully" }