---
updatedAt: 2025-06-25T12:46:04.000Z
agentTools:
projectIndex: https://developers.evrythng.com/llms.txt
---
# Files
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:
1. Creating a `FileDocument` metadata resource detailing the file's format and its `id`.
2. 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`](#section-filedocument-data-model) 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 [`FileDocument`](#section-filedocument-data-model)s 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`](#section-filedocument-data-model) was [created](#section-create-remote-file-metadata).
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`](#section-filedocument-data-model) was [created](#section-create-remote-file-metadata).
***
## 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](#section-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](#section-read-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.