--- title: Create a data collection slug: q65f3128 canonical_url: https://docs.coveo.com/en/q65f3128/ collection: data-collections source_format: adoc --- # Create a data collection Before you can add [items](https://docs.coveo.com/en/210.md) to a [data collection](https://docs.coveo.com/en/q65b0594.md), 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](https://docs.coveo.com/en/o8rb0139.md) 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](https://docs.coveo.com/en/228.md) required for managing data collections. These [privileges](https://docs.coveo.com/en/228.md) alone don't grant the ability to edit the content of a data collection using the Stream API. See [Manage privileges](https://docs.coveo.com/en/3151.md) and [Privilege reference](https://docs.coveo.com/en/1707.md) for details. | 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](https://docs.coveo.com/en/3151.md#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:** ```http POST https://platform.cloud.coveo.com/api/private/organizations//data-collections HTTP/1.1 ​ Content-Type: application/json Authorization: Bearer ``` In the request path: * Replace `` with your [organization ID](https://docs.coveo.com/en/148.md). In the `Authorization` HTTP header: * Replace `` with an [API key](https://docs.coveo.com/en/1718.md#create-a-custom-key) that has the [required privileges](#required-privileges) to push content to the data collection. **Payload:** ```json { "name": "", <1> "dataCollectionType": "", <2> "config": { <3> "trackingId": "" }, "schemaVersion": <4> } ``` <1> (Required) Replace `` with the name of the data collection. Choose a descriptive name containing only letters, numbers, underscores, and hyphens. <2> (Required) Replace `` with the type of the data collection. For now, the only supported value is `OFFLINE_PURCHASES`. <3> (Required) The `config` object contains collection type-specific configuration properties. For offline purchases, replace `` with the [tracking ID](https://docs.coveo.com/en/q2490232.md#tracking-ids) to associate with the data collection. This value is used to associate ingested [items](https://docs.coveo.com/en/210.md) with a specific tracking ID without requiring it to be specified in every [item](https://docs.coveo.com/en/210.md) of [update](https://docs.coveo.com/en/q6980563.md#step-2-upload-the-update-into-the-file-container) and [rebuild](https://docs.coveo.com/en/q6980563.md#step-2-upload-items-into-the-stream) payloads. The tracking ID must be set up beforehand using the [Set up storefronts and properties](https://docs.coveo.com/en/q2490232.md) procedure. <4> (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](https://docs.coveo.com/en/210.md) 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`. ```http POST https://platform.cloud.coveo.com/api/private/organizations/barcasportsmcy01fvu/data-collections HTTP/1.1 ​ Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` ```json { "name": "Offline-purchases-Canada", "dataCollectionType": "OFFLINE_PURCHASES", "config": { "trackingId": "barca_canada" <1> } } ``` <1> Specify the tracking ID associated with your [storefront and property setup](https://docs.coveo.com/en/q2490232.md#tracking-ids). ```json { "id": "3abf2472-9dcc-4ff8-83ac-8659c61d7a4d", <1> "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" } ``` <1> 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:** ```http GET https://platform.cloud.coveo.com/api/private/organizations//data-collections?filter=&page=&perPage=&sortBy=&order= HTTP/1.1 Authorization: Bearer ``` **Request parameters**
Details In the request path: * Replace `` with your [organization ID](https://docs.coveo.com/en/148.md). In the query string (all optional): * Replace `` with a string to filter results by name. Omit the parameter to return all data collections. * Replace `` with the zero-based page number to retrieve. Default: `0`. * Replace `` with the number of items per page (minimum `1`, maximum `100`). Default: `25`. * Replace `` with the field to sort results by. Possible values: `NAME`, `DATA_COLLECTION_TYPE`. Default: `NAME`. * Replace `` with the sort direction. Possible values: `ASC`, `DESC`. Default: `ASC`. In the `Authorization` HTTP header: * Replace `` with an access token that grants the [required privileges](#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. ```json { "pagination": { "page": 0, "perPage": 25, "totalItems": 2, "totalPages": 1 }, "items": [ { "id": "3abf2472-9dcc-4ff8-83ac-8659c61d7a4d", <1> "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", <1> "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" } ] } ``` <1> 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:** ```http DELETE https://platform.cloud.coveo.com/api/private/organizations//data-collections/ HTTP/1.1 Authorization: Bearer ``` **Request parameters**
Details In the request path: * Replace `` with your [organization ID](https://docs.coveo.com/en/148.md). * Replace `` with the unique identifier of the data collection to delete. You can [list your data collections](#list-data-collections) to find their IDs. In the `Authorization` HTTP header: * Replace `` with an access token that grants the [required privileges](#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](https://docs.coveo.com/en/q6980563.md).