Pivot collections API
You can use the Pivot collections API to create, view, and modify collections of Pivot data cubes and dashboards.
Pivot must be running in native users mode.
Get all collections
Returns a list of all collections.
URL
GET /api/v2/collections
Sample request
curl -X GET 'http://PIVOT_URL/api/v2/collections' \
--header 'x-imply-api-token:<token>'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample response
Show sample response
{
"values": [
{
"id": "08cf",
"name": "Wikipedia France",
"description": "Data cubes and dashboards related to French channels",
"assets": [
{
"id": "4134",
"type": "dataCube"
},
{
"id": "6713",
"type": "dashboard"
},
{
"id": "c126",
"type": "dashboard"
}
],
"createdAt": "2025-05-27T10:04:52.471Z",
"createdBy": "admin@example.com",
"updatedAt": "2025-05-27T10:05:08.944Z",
"updatedBy": "admin@example.com"
},
{
"id": "6550",
"name": "Wikipedia Germany",
"description": "Data cubes and dashboards related to German channels",
"assets": [
{
"id": "360d",
"type": "dataCube"
},
{
"id": "7ad0",
"type": "dashboard"
},
{
"id": "285a",
"type": "dashboard"
}
],
"createdAt": "2025-05-27T10:05:22.645Z",
"createdBy": "admin@example.com",
"updatedAt": "2025-05-27T10:05:31.536Z",
"updatedBy": "admin@example.com"
},
{
"id": "7c98",
"name": "KTTM",
"description": "Koalas to the Max assets",
"assets": [
{
"id": "kttm4410",
"type": "dataCube"
},
{
"id": "7659",
"type": "dashboard"
},
{
"id": "c34a",
"type": "dashboard"
}
],
"createdAt": "2025-05-27T10:05:46.606Z",
"createdBy": "admin@example.com",
"updatedAt": "2025-05-27T10:05:53.989Z",
"updatedBy": "admin@example.com"
}
]
}
Get a collection
Returns a collection with a specified ID.
URL
GET /api/v2/collections/{id}
Sample request
curl -X GET 'http://PIVOT_URL/api/v2/collections/7c98' \
--header 'x-imply-api-token:<token>'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "Collection with ID \"7c90\" not found" |
Sample response
{
"id": "7c98",
"name": "KTTM",
"description": "Koalas to the Max assets",
"assets": [
{
"id": "kttm4410",
"type": "dataCube"
},
{
"id": "7659",
"type": "dashboard"
},
{
"id": "c34a",
"type": "dashboard"
}
],
"createdAt": "2025-05-27T10:05:46.606Z",
"createdBy": "admin@example.com",
"updatedAt": "2025-05-27T10:05:53.989Z",
"updatedBy": "admin@example.com"
}
Create a collection
Creates a collection with a specified name and optional description. See Add assets to a collection to add data cubes and dashboards after you create the collection.
URL
POST /api/v2/collections
Sample request
curl -X POST 'http://PIVOT_URL/api/v2/collections' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "KTTM assets",
"description": "Data cubes and dashboards related to Koalas to the Max"
}'
Success response
Code | Description |
---|---|
201 | "status": "created" |
Sample error response
Code | Example body |
---|---|
400 Bad Request | "message": "must have required property 'name'" |
Sample response
{
"id": "c335",
"name": "KTTM assets",
"description": "Data cubes and dashboards related to Koalas to the Max",
"assets": [],
"createdAt": "2025-05-27T10:22:30.134Z",
"createdBy": "API",
"updatedAt": "2025-05-27T10:22:30.134Z",
"updatedBy": "API"
}
Add assets to a collection
Adds assets to a collection with a specified ID.
URL
POST /api/v2/collections/{id}/assets
Sample request
The following request adds a data cube and a dashboard to the collection with ID c335
.
The collection already contains one data cube and one dashboard.
curl -X POST 'http://PIVOT_URL/api/v2/collections/c335/assets' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/merge-patch+json' \
--data-raw '{
"values": [
{
"id": "kttm5690",
"type": "dataCube"
},
{
"id": "8844",
"type": "dashboard"
}
]
}'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "Collection with ID \"c334\" not found" |
Sample response
{
"id": "c335",
"name": "KTTM assets",
"description": "Data cubes and dashboards related to Koalas to the Max",
"assets": [
{
"id": "kttm4410",
"type": "dataCube"
},
{
"id": "c34a",
"type": "dashboard"
},
{
"id": "kttm5690",
"type": "dataCube"
},
{
"id": "8844",
"type": "dashboard"
}
],
"createdAt": "2025-05-27T10:22:30.134Z",
"createdBy": "API",
"updatedAt": "2025-05-27T10:22:30.134Z",
"updatedBy": "API"
}
Remove assets from a collection
Removes assets from a collection with a specified ID.
URL
DELETE /api/v2/collections/{id}/assets/{assetType}/{assetId}
Sample request
The following request removes the data cube with ID kttm5690
from the collection with ID c335
.
curl -X DELETE 'http://PIVOT_URL/api/v2/collections/c335/assets/dataCube/kttm5690' \
--header 'x-imply-api-token:<token>'
Success response
Code | Description |
---|---|
204 | "status": "no content" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "Collection with ID \"c334\" not found" |
Update a collection
Updates the name or description of a collection with a specified ID.
Pivot retains the details of properties not specified in the request.
For example, to update name
and keep the same description
, you only need to specify the updated name
in the request.
See Add assets to a collection and Remove assets from a collection for information on adding and removing collection assets.
URL
PATCH /api/v2/collections/{id}
Sample request
The following example request updates the name
and description
of the collection with ID c335
.
curl -X PATCH 'http://PIVOT_URL/api/v2/collections/c335' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/merge-patch+json' \
--data-raw '{
"name": "Koalas to the Max assets",
"description": "Dashboards related to Koalas to the Max"
}'
Success response
Code | Description |
---|---|
200 | "status": "ok" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "Collection with ID \"c334\" not found" |
Sample response
{
"id": "c335",
"name": "Koalas to the Max assets",
"description": "Dashboards related to Koalas to the Max",
"assets": [
{
"id": "2399",
"type": "dashboard"
},
{
"id": "7659",
"type": "dashboard"
}
],
"createdAt": "2025-05-27T10:21:15.025Z",
"createdBy": "API",
"updatedAt": "2025-05-27T11:17:38.715Z",
"updatedBy": "API"
}
Delete a collection
Deletes a collection with a specified ID.
URL
DELETE /api/v2/collections/{id}
Sample request
curl -X DELETE 'http://PIVOT_URL/api/v2/collections/c335' \
--header 'x-imply-api-token:<token>'
Success response
Code | Description |
---|---|
204 | "status": "no content" |
Sample error response
Code | Example body |
---|---|
404 Not Found | "error": "Collection with ID \"c334\" not found" |