Create a data collection

This is for:

In this article

Prerequisites
Create a data collection
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.

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
View data collections	Organization	Data collection	View
Organization	Organization	View
Create, edit, and delete data collection configurations	Organization	Data collection	Edit

Actions

Service

Domain

Required access level

View data collections

Organization

Data collection

View

Organization

View

Create, edit, and delete data collection configurations

Organization

Data collection

Edit

Note

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-4ft8-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.

Delete a data collection

To delete a data collection, use a DELETE request to https://platform.cloud.coveo.com/api/private/organizations/<MyOrganizationId>/data-collections/<MyCollectionId>. You must provide your organization ID and the data collection ID in the request path.

To retrieve the list of data collections and their IDs, use a GET request to https://platform.cloud.coveo.com/api/private/organizations/<MyOrganizationId>/data-collections. You must provide your organization ID in the request path.

What’s next?

Ingest data into a data collection.