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 POST /files HTTP request.

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

Use the Create a file container operation to create an Amazon S3 file container for a specific Coveo organization:

Request template

Request definition

POST https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer <MyAccessToken>

Request body

{}

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:

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

Successful response - 201 Created

{
    "uploadUri": "<UPLOAD-URI>", 1
    "fileId": "b5e8767e-8f0d-4a89-9095-1127915c89c7", 2
    "requiredHeaders": { 3
        "x-amz-server-side-encryption": "AES256",
        "Content-Type": "application/octet-stream"
    }
}
1 The uploadUri property contains a pre-signed URI to which you can send a PUT request whose binary content must be your request body or item 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 specific Coveo organization.

Note

Request definition

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

Request body

{}
Note

Successful response - 201 Created

{
  "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"
  }
}