Create a file container

This is for:

Developer System Administrator

A file container is a temporary, private, and encrypted Amazon S3 data structure you can use to safely upload content that you intend to push into a Push source or security identity provider. You’ll typically use a file container when you want to push:

This article provides an overview of the Create a file container request.

Sequence diagram for POST files request | Coveo
Sequence diagram highlighting the Create a file container request in the context of a batch update sequence and illustrating how the Coveo indexing pipeline handles the batch update.

Request template

US East region 
POST https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>
Canada region 
POST https://api-ca.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>
Ireland region 
POST https://api-eu.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>
Australia region 
POST https://api-au.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
​
Accept: application/json
Authorization: Bearer <MyAccessToken>

Request parameters:

Parameters

In the request path:

In the query string:

  • Optionally, set useVirtualHostedStyleUrl to true if you want the service to return a virtual hosted-style URL, such as coveo-nprod-customerdata.s3.amazonaws.com/.... The default value is currently false, which means that the service returns path-style URLs, such as s3.amazonaws.com/coveo-nprod-customerdata/....

    Important

    The useVirtualHostedStyleUrl query string parameter will soon be deprecated as part of the path-style URL deprecation. From this point onwards, the service will only return virtual hosted-style URLs.

In the Authorization HTTP header:

Request body: None

Successful response: 201 Created

The body of a successful response contains important information about the temporary, private, and encrypted Amazon S3 file container that you just created:

{
    "uploadUri": "<UPLOAD_URI>", 1
    "fileId": "<FILE_ID>", 2
    "requiredHeaders": { 3
        "x-amz-server-side-encryption": "AES256",
        "Content-Type": "application/octet-stream"
    }
}
1 The uploadUri property contains a pre-signed URI to make a PUT request to when pushing item or security identity data.
Notes

  • The Amazon S3 file container applies AES-256 server-side encryption to your data.

  • The file container is automatically deleted as soon as its content has been successfully forwarded to the service.

  • The uploadUri automatically expires after 60 minutes.

Therefore, it’s safe to upload sensitive information into the Amazon S3 file container.
2 The fileId property contains the unique identifier of your file container.
3 The requiredHeaders property contains the required HTTP headers for sending a PUT request to the uploadUri.

Path-style URL deprecation

Amazon is deprecating path-style URLs, such as s3.amazonaws.com/coveo-nprod-customerdata/..., in favour of virtual hosted-style URLs, such as coveo-nprod-customerdata.s3.amazonaws.com/.... Accordingly, the Push API will also deprecate path-style URLs.

You can already test and use the new hosted-style URL format by setting the useVirtualHostedStyleUrl query parameter to true. If you’re using the Crawling Module or Coveo for Sitecore, you can update to the latest version to test the new behavior.

Virtual hosted-style URLs let you be more precise regarding the list of outbound URL addresses to allow. For example, if your primary deployment region is US East, you can allowlist coveo-nprod-customerdata.s3.amazonaws.com rather than s3.amazonaws.com. The following table lists the virtual hosted-style domain for each primary region:

Main region Virtual hosted-style domain

US East

coveo-nprod-customerdata.s3.amazonaws.com

Canada

coveo-cprd-customerdata.s3.ca-central-1.amazonaws.com

Ireland

coveo-iprd-customerdata.s3.eu-west-1.amazonaws.com

Australia

coveo-aprd-customerdata.s3.ap-southeast-2.amazonaws.com

For HIPAA organizations, the virtual hosted-style domain name is coveo-nhipaa-customerdata.s3.amazonaws.com.

Sample request

The following example shows how to create a file container for a Coveo organization in the US East region.

POST https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/files?useVirtualHostedStyleUrl=true HTTP/1.1
​
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Request body: None

Response:

{
  "uploadUri": "link:https://coveo-nprod-customerdata.s3.amazonaws.com/proda/blobstore/mycoveocloudv2organizationg8tp8wu3/b5e8767e-8f0d-4a89-9095-1127915c89c7[...]",
  "fileId": "b5e8767e-8f0d-4a89-9095-1127915c89c7",
  "requiredHeaders": {
    "x-amz-server-side-encryption": "AES256",
    "Content-Type": "application/octet-stream"
  }
}