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

When creating a user, you can add "sendWelcomeEmail": true to the body of the request to have a welcome email sent to the new user with a password change prompt.

The default template for the welcome email is in the Pivot configuration file:

emailTemplate:
  - name: invite
    subject: Create your pivot account
    html: 'Please use this link to set your password: ${linkProtocol}://${linkHost}${linkPath}'

To specify a custom invite email template, provide an entry in the emailTemplates block with name invite.

By default, if you set sendWelcomeEmail to true, the Host HTTP header to populate the ${linkHost}${linkPath} in the link sent to your new users. You can override this default URL by setting clientUrl to the URL you want to use. You can use clientUrl when the request hostname differs from the URL you want to use, such as when there are load balancers serving your request.

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,
  "clientUrl": "http://clienturl.com"

}' 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.03

Data cubes

Dashboards

Endpoints

Read

Create

Update

Delete