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"