The File API manages storage and retrieval of files. An EVRYTHNG file resource only contains the metadata for the file (name, type, etc.). The actual file itself is uploaded separately as part of the workflow detailed below.

The process for storing a file within the Platform consists of two steps:

Creating a FileDocument metadata resource detailing the file's format and its id.
Uploading the file itself to the uploadUrl specified in the created FileDocument in a followup request.

The file itself can then be read back from the metadata resource's `contentUrl` property.

API Status
General Availability:
`/files`
`/files/:fileId`

FileDocument Data Model

A FileDocument holds information about a file stored on a remote platform. This includes signed upload and download URLs for a file, and also whether the file has 'private' or 'public' access on remote storage.

See also: ScopesDocument

Filterable Fields

This resource type can be filtered using the following fields and operators.

Create Remote File Metadata

Use this endpoint to create a metadata record for a file to be uploaded. This operation is the basis for a remote file upload. A successful HTTP POST will create a FileDocument record with a unique ID and a transient uploadUrl field.

This signed uploadUrl can then be used by a client with an HTTP PUT request to do the actual upload to remote storage. The uploadUrl will expire after 30 minutes. The input payload to this endpoint should also contain a setting for the privateAccess field to indicate whether the file should have 'private' or 'public' access on remote storage.

Read Metadata for All Remote Files

Use this endpoint to get a list of FileDocuments associated with this account ID. The retrieved file metadata will have (among other attributes), a file's unique ID, and a transient contentUrl field which can be used to download the actual file represented by the resource using an HTTP GET request.

The value of the privateAccess boolean field will indicate whether the file has public-read or private access on remote storage. The result may be paginated if there are more than 30 items.

This endpoint also supports filtering by name and tags filters. Details of filters can be found on the Filters page.

Read Remote File Metadata by ID

Use this endpoint to get metadata for a specific remote file by ID. The fileId path parameter should be the value returned when the FileDocument was created.

The retrieved file metadata will have (among other attributes), a transient contentUrl field which can be used to download the physical file using an HTTP GET request. The value of the privateAccess boolean field will indicate whether the file has 'public' or 'private' access on remote storage.

Delete Remote File by ID

Use this endpoint to delete a remote file by ID. The fileId path parameter should be the id value returned when the FileDocument was created.

File Upload Workflow

In order to upload a file you need to get a signed uploadUrl, which can then be used with an HTTP PUT request to perform a multipart or binary data upload.

Step 1: Create Remote File Metadata and note the uploadUrl in the response, including its query parameters.

Step 2: Perform an HTTP PUT request to the uploadUrl attribute, and specify the x-amz-acl header as private or public-read, depending on the file resource's privateAccess field. Make sure to also match the Content-Type also specified previously.

The example below shows uploading a text file to the Files API. For the cURL example, the --data-binary flag will also work for other files types, such as images.

File Download Workflow

In order to download a previously uploaded remote file you need to get a contentUrl by performing an HTTP GET request with the file's ID. The contentUrl can then be used in a subsequent HTTP GET request to download the actual file.

Step 1: Retrieve remote file metadata by ID.

Step 2: Perform an HTTP GET request on the contentUrl using the correct value of the x-amz-acl header, either "private" or "public-read", that was used when the file was uploaded. You must also specify the correct Content-Type header for the uploaded file.