Create a data collection

This is for:

In this article

Prerequisites
Create a data collection
List data collections
Delete a data collection
What’s next?

Before you can add items to a data collection, you must create the data collection in the Coveo Platform.

Though data collections currently support a single type, the data collection creation step serves the following purposes:

Declaring the data collection type, which determines the schema that items in the data collection must adhere to.
Providing configuration parameters, such as the tracking ID for offline purchases, to contextualize the data collection.
Obtaining the unique identifier of the data collection to use later in Stream API calls for item management.

This article explains how to create a data collection using the Data Collections private API and provides information about other data collection management requests, including listing and deleting data collections.

Prerequisites

Make sure you have an API key using the Custom template with the required privileges. The following table indicates the API key privileges required for managing data collections. These privileges alone don’t grant the ability to edit the content of a data collection using the Stream API. See Manage privileges and Privilege reference for details.

Actions	Service	Domain	Required access level
Create, edit, and delete data collection configurations	Content	Data collections	Edit

Actions

Service

Domain

Required access level

Create, edit, and delete data collection configurations

Content

Data collections

Edit

Notes

The Edit privilege on the Data collection domain automatically grants the ability to create data collections. See Can Create ability dependence for more information.

Create a data collection

Use the Create a data collection HTTP request template and sample that follow to create a data collection.

Request template:

POST https://platform.cloud.coveo.com/api/private/organizations/<MyOrganizationId>/data-collections  HTTP/1.1

Content-Type: application/json
Authorization: Bearer <MyAccessToken>

In the request path:

Replace <MyOrganizationId> with your organization ID.

In the Authorization HTTP header:

Replace <MyAccessToken> with an API key that has the required privileges to push content to the data collection.

Payload:

{
  "name": "<DATA_COLLECTION_NAME>", 
  "dataCollectionType": "<DATA_COLLECTION_TYPE>", 
  "config": { 
    "trackingId": "<TRACKING_ID>"
  },
  "schemaVersion": <SCHEMA_VERSION> 
}

	(Required) Replace `<DATA_COLLECTION_NAME>` with the name of the data collection. Choose a descriptive name containing only letters, numbers, underscores, and hyphens.
	(Required) Replace `<DATA_COLLECTION_TYPE>` with the type of the data collection. For now, the only supported value is `OFFLINE_PURCHASES`.
	(Required) The `config` object contains collection type-specific configuration properties. For offline purchases, replace `<TRACKING_ID>` with the tracking ID to associate with the data collection. This value is used to associate ingested items with a specific tracking ID without requiring it to be specified in every item of update and rebuild payloads. The tracking ID must be set up beforehand using the Set up storefronts and properties procedure.
	(Optional) The version integer of the data collection validation schema to use. If nothing is specified, the latest version will be used by default. Specifying a schema version may be useful to prevent breaking changes when Coveo releases new schema versions.

Successful response: 201 Created

The body of a successful response contains the unique identifier of the data collection (id) to use in future Stream API calls for data collection item management.

Sample request:

The following sample request creates a data collection of type OFFLINE_PURCHASES with the name Offline-purchases-Canada and the tracking ID barca_canada.

POST https://platform.cloud.coveo.com/api/private/organizations/barcasportsmcy01fvu/data-collections  HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Sample payload for offline purchases data collection

{
  "name": "Offline-purchases-Canada",
  "dataCollectionType": "OFFLINE_PURCHASES",
  "config": {
    "trackingId": "barca_canada" 
  }
}

Specify the tracking ID associated with your storefront and property setup.

Sample response body

{
  "id": "3abf2472-9dcc-4ff8-83ac-8659c61d7a4d", 
  "name": "Offline-purchases-Canada",
  "dataCollectionType": "OFFLINE_PURCHASES",
  "config": {
    "trackingId": "barca_canada"
  },
  "schemaVersion": 1,
  "information": {
    "objectCount": 0
  },
  "createdDateTime": 1781108760762,
  "createdBy": "msmith@barca.com",
  "lastModifiedDateTime": 1781108760762,
  "lastModifiedBy": "msmith@barca.com"
}

The data collection unique identifier.

List data collections

Use the List data collections HTTP request template to retrieve the list of data collections in your organization along with their IDs.

Request template:

GET https://platform.cloud.coveo.com/api/private/organizations/<MyOrganizationId>/data-collections?filter=<MyFilter>&page=<MyPage>&perPage=<MyPerPage>&sortBy=<MySortBy>&order=<MyOrder>  HTTP/1.1

Authorization: Bearer <MyAccessToken>

Request parameters

In the request path:

Replace <MyOrganizationId> with your organization ID.

In the query string (all optional):

Replace <MyFilter> with a string to filter results by name. Omit the parameter to return all data collections.
Replace <MyPage> with the zero-based page number to retrieve. Default: 0.
Replace <MyPerPage> with the number of items per page (minimum 1, maximum 100). Default: 25.
Replace <MySortBy> with the field to sort results by. Possible values: NAME, DATA_COLLECTION_TYPE. Default: NAME.
Replace <MyOrder> with the sort direction. Possible values: ASC, DESC. Default: ASC.

In the Authorization HTTP header:

Replace <MyAccessToken> with an access token that grants the required privileges in the target organization.

Successful response: 200 OK

The body of a successful response contains a pagination object with result count and paging metadata, and an items array of data collection objects.

Sample response body

{
  "pagination": {
    "page": 0,
    "perPage": 25,
    "totalItems": 2,
    "totalPages": 1
  },
  "items": [
    {
      "id": "3abf2472-9dcc-4ff8-83ac-8659c61d7a4d", 
      "name": "Offline-purchases-Canada",
      "dataCollectionType": "OFFLINE_PURCHASES",
      "config": {
        "trackingId": "barca_canada"
      },
      "schemaVersion": 1,
      "information": {
        "objectCount": 1250
      },
      "createdDateTime": 1781108760762,
      "createdBy": "msmith@barca.com",
      "lastModifiedDateTime": 1781195160762,
      "lastModifiedBy": "msmith@barca.com"
    },
    {
      "id": "7c6ade2a-5f2b-48d9-884e-e5a5a418bc58", 
      "name": "Offline-purchases-US",
      "dataCollectionType": "OFFLINE_PURCHASES",
      "config": {
        "trackingId": "barca_us"
      },
      "schemaVersion": 1,
      "information": {
        "objectCount": 830
      },
      "createdDateTime": 1781182525000,
      "createdBy": "msmith@barca.com",
      "lastModifiedDateTime": 1781268925000,
      "lastModifiedBy": "msmith@barca.com"
    }
  ]
}

Collection IDs.

Delete a data collection

Use the Delete a data collection HTTP request template to delete a data collection and all of its items.

Request template:

DELETE https://platform.cloud.coveo.com/api/private/organizations/<MyOrganizationId>/data-collections/<MyCollectionId>  HTTP/1.1

Authorization: Bearer <MyAccessToken>

Request parameters

In the request path:

Replace <MyOrganizationId> with your organization ID.
Replace <MyCollectionId> with the unique identifier of the data collection to delete. You can list your data collections to find their IDs.

In the Authorization HTTP header:

Replace <MyAccessToken> with an access token that grants the required privileges in the target organization.

Successful response: 204 No Content

A successful response has no body.

What’s next?

Ingest data into a data collection.