ActivateAuthenticateAmplify
DashboardSupportDeveloper Blog

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

Jump To ↓

FileDocument Data Model
Create Remote File Metadata
Read Metadata for All Remote Files
Read Remote File Metadata by ID
Delete Remote File by ID
File Upload Workflow
File Download Workflow

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.

.id (string, read-only)
    The ID of this resource.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.tags (array of string)
    Array of string tags associated with this resource.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields
    associated with the resource.

.uploadUrl (string, read-only)
    The URL to upload file data to with an HTTP `PUT` request.
    Will expire after 30 mins.

.contentUrl (string, read-only)
    The URL the file is available at for download.

.name (string, required)
    Name of the file. This is unique to the account, allowing a
    file to be overwritten.

.type (string, required)
    The MIME type of the file. Must match the Content-Type
    header used when uploading the file content.

.privateAccess (boolean, required)
    A boolean flag indicating whether a file should have
    `private` or `public` access on remote storage.

.size (integer, read-only)
    The size of the uploaded file in bytes.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object containing remote file metadata.",
  "required": ["name", "type", "privateAccess"],
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 256,
        "maximum": 60
      }
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "uploadUrl": {
      "type": "string",
      "description": "The URL to upload file data to with an HTTP `PUT` request. Will expire after 30 mins.",
      "readOnly": true
    },
    "contentUrl": {
      "type": "string",
      "description": "The URL the file is available at for download.",
      "readOnly": true
    },
    "name": {
      "type": "string",
      "description": "Name of the file. This is unique to the account, allowing a file to be overwritten."
    },
    "type": {
      "type": "string",
      "description": "The MIME type of the file. Must match the Content-Type header used when uploading the file content."
    },
    "privateAccess": {
      "type": "boolean",
      "description": "A boolean flag indicating whether a file should have `private` or `public` access on remote storage."
    },
    "size": {
      "type": "integer",
      "description": "The size of the uploaded file in bytes.",
      "readOnly": true
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": { "type": "string" }
        }
      }
    }
  },
  "x-filterable-fields": [
    {
      "name": "name",
      "type": "string",
      "operators": ["="]
    },
    {
      "name": "tags",
      "type": "list of string",
      "operators": ["="]
    }
  ]
}

{
  "id": "UkHsQB7C6msEhqaaR2tsQbWh",
  "createdAt": 1487860949665,
  "updatedAt": 1487860949665,
  "uploadUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/example-file.js?...",
  "contentUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/example-file.js",
  "size": 35862,
  "name": "brand-logo.png",
  "type": "image/png",
  "customFields": {
    "factory": "488974"
  },
  "privateAccess": false
}

See also: ScopesDocument

Filterable Fields

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

FieldTypeOperators
nameString=
tagsList of string=

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.

POST /files
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

FileDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/files' \
  -d '{
    "name": "brand-logo.png",
    "type": "image/png",
    "tags": ["brand assets"],
    "privateAccess": false
  }'

const payload = {
  name: 'my_file1.txt',
  type: 'text/plain',
  privateAccess: false
};

operator.file().create(payload)
  .then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://$EVT_API_DOMAIN/files/U2k9enU2BD8RQKaaagME5dFn

{
  "id": "U2k9enU2BD8RQKaaagME5dFn",
  "createdAt": 1485785656730,
  "updatedAt": 1485785656730,
  "uploadUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/brand-logo.png?AWSAccessKeyId=AKIAID2MOF7RYNLLMH7Q&Expires=1485787456&Signature=YWBUFgcyCKfcTxEg9tzxAxmvP%2FU%3D",
  "name": "brand-logo.png",
  "type": "image/png",
  "tags": ["brand assets"],
  "privateAccess": false
}

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.

🚧

Important

If the privateAccess flag is set to true, then the contentUrl will expire after 30 minutes.

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

GET /files
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/files"

operator.file().read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UkYqry34eDswtKawaYMqwfbr",
    "createdAt": 1484575386979,
    "updatedAt": 1484575386979,
    "uploadUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/brand-logo.png?AWSAccessKeyId=AKIAID2MOF7RYNLLMH7Q&Expires=1485788741&Signature=eyJvv7wFCl8AFaG9G%2BDYapUdoZc%3D",
    "contentUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/brand-logo.png",
    "size": 67,
    "name": "brand-logo.png",
    "type": "image/png",
    "privateAccess": false
  }
]

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.

GET /files/:fileId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/files/UFm5cMg7Bgsat5aawFS4nhHt'

const fileId = 'UFm5cMg7Bgsat5aawFS4nhHt';

operator.file(fileId).read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UFm5cMg7Bgsat5aawFS4nhHt",
    "createdAt": 1484575386979,
    "updatedAt": 1484575386979,
    "uploadUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/brand-logo.png?AWSAccessKeyId=AKIAID2MOF7RYNLLMH7Q&Expires=1485788741&Signature=eyJvv7wFCl8AFaG9G%2BDYapUdoZc%3D",
    "contentUrl": "https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg39QCy9dsSddN8xhwnb/brand-logo.png",
    "size": 67,
    "name": "brand-logo.png",
    "type": "image/png",
    "privateAccess": false
  }
]

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.

❗️

Important

This endpoint will physically delete the file on remote storage, and will also remove the file's metadata record on the platform.

DELETE /files/:fileId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/files/UFm5cMg7Bgsat5aawFS4nhHt'

const fileId = 'UFm5cMg7Bgsat5aawFS4nhHt';

operator.file(fileId).delete()
  .then(() => console.log('Deleted'));

HTTP/1.1 200 OK

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.

PUT :uploadUrl
Content-Type: text/plain
x-amz-acl: public-read


- - - - - -WebKitFormBoundaryKJ2T3DyoTYBx6Byd
Content-Disposition: form-data; name="file"; filename="my_file.txt"
Content-Type: text/plain

My remote file text content


- - - - - -WebKitFormBoundaryKJ2T3DyoTYBx6Byd--

curl -H "Content-Type: text/plain" \
  -H "x-amz-acl: public-read" \
  -X PUT 'https://s3.amazonaws.com/evtcdn_02/2/uf/UhpHrg3837hgdsSddN8xhwnb/brand-logo.png?AWSAccessKeyId=AKIHD8YH9F7RYNLLMH7Q&Expires=1486726308&Signature=op3MlVJ46HF53%2F%2BDRKqAV2cJtYM%3D' \
  --data-binary @brand-logo.png

HTTP/1.1 200 OK

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.

GET :contentUrl
Content-Type: text/plain
x-amz-acl: private (or public-read)