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 you intend to push into a Push source or security identity provider. You will typically use a file container when you want to push:

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

Request template

POST https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1

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

Payload

{}

In the request path:

In the query string:

  • Optionally, set useVirtualHostedStyleUrl to true if you want the service to return the URL in virtual hosted-style (for example, coveo-nprod-customerdata.s3.amazonaws.com/...). Default value is currently false, which means that the service returns path-style URLs (for example, 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 you just created:

Tip

Successful response - 200 OK

{
    "uploadUri": "<UPLOAD-URI>",
    "requiredHeaders": {
        "x-amz-server-side-encryption": "AES256",
        "Content-Type": "application/octet-stream"
    }
}

  • 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 (see Advanced Encryption Standard).

    • 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 perfectly safe to upload sensitive information into the Amazon S3 file container.

  • The fileId property contains the unique identifier of your file container.

  • 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 (for example, s3.amazonaws.com/coveo-nprod-customerdata/...) in favour of virtual hosted-style URLs (for example, 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 behaviour.

Virtual hosted-style URLs allow you to 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-cprod-customerdata.s3.ca-central-1.amazonaws.com

Ireland

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

Australia

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

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

Sample request

Creating a file container for a specific Coveo organization

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

Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{}

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