Skip to main content

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

CodeDescription
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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
201"status": "created"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
204"status": "no content"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
204"status": "no content"

Sample error response

CodeExample body
404 Not Found"error": "Collection with ID \"c334\" not found"