Skip to content

Developers · Assets

Uploads

Last updated 1 November 2026

Uploads are used to store the URL and metadata of a file that you uploaded.

Defining uploads

You can define uploads by adding a database field with set to , for example:

- name: document
  type: upload

Options

The database field takes an extra parameter, which allows you to configure it.

Option Description
The file is made publicly available if set to (default). It is automatically generated by GraphQL when you provide the argument to the field in the PropertiesInterface GraphQL interface. A signature generated on the server side is needed to access the file if set to .
Allows you to set server-side validation for minimum (using the key) and maximum file size (using the key) in kilobytes. For example, will set the max input file size (not the generated version) to 2MB.
Allows you to define up to 10 versions of the image. You can define multiple processing instructions for each version - compression, resizing, etc. Visit the section on version options in this article, just after this table. This option is ignored if the uploaded file is not an image.
Allows you to set the Cache-Control header returned with the file. Default is
Allows you to set the Content-Disposition header. The default is  which you can change to an .

Versions

Versions are defined in yml as an array. Each element must have a and a list of options you want to use. Please note that not all combinations make sense. An example configuration might look like this:

properties:
- name: photo
  type: upload
  options:
    content_length:
      lte: 2048  # maximum input file size will be 2048 KB
    versions:
      - name: large_bw    # version name
        output:
          format: jpeg    # output format
          quality: 70     # output quality
        resize:
          width: 1600     # width of the image - in this case max width
          height: 1200    # height of the image - in this case max height
          fit: inside     # preserve aspect ratio, do not crop the image, make sure all pixels are within viewport
          without_enlargement: false              # if image is smaller than width/height, do not enlarge it
        manipulate:
          greyscale: true   # make image greyscale (similar to css "filter: grayscale(1)")
          blur: 20          # blur using gaussian mask (similar to css "filter: blur(1.5rem)")
          flatten: red      # merge alpha transparency channel (if exists) with given color
      - name: small
        output:
          format: webp
          quality: 80
        resize:
          width: 640
          height: 480
          fit: cover
          position: top   # define the gravity direction or strategy when cropping the image using fit cover or contain
      - name: thumb
        output:
          format: png
          quality: 80
        resize:
          width: 200
          fit: contain
          background: "rgba(255, 255, 255, 0.5)"  # if the resized image is not covering whole viewport, set background color, can be in hex format (ie. #f0f0f0), or rgb (ie. rgb(255, 255, 255))
      - name: center
        output:
          format: jpeg
          quality: 100
        resize:
          height: 400
          width: 400
          fit: cover

Output

Output parameter options are detailed in the table below:

Output option Description
[String]Force a file extension for an output image; leave blank if you want to keep the format of the original image.
[Int]

Quality of the output. being the best (and largest in terms of size). Keep in mind compression has different effects on different formats. Default values are as follows:

  • PNG:
  • WEBP:
  • JPEG:
[Boolean] Only - use progressive (interlace) scan. Default:

Resize

Resize parameter options are outlined in the table below:

Resize optionDescription
[Int] The width that the user passed as a reference. Other parameters are left to determine the size (like height) if left undefined.
[Int] The height that the user passed as a reference. Other parameters are left to determine the size (like width) if left undefined.
[String]

This option controls how the image should be resized to fit both provided dimensions. The following options are available:

  • : Crop to cover both provided dimensions (the default).
  • : Embed within both provided dimensions.
  • : Ignore the input aspect ratio and stretch to both provided dimensions.
  • : Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to those specified.
  • : Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified. Some of these values are based on the object-fit CSS property.
[String]

Position to use when the is set to or . Default value: . The following options are available:
[String|Object] Background color used when using a fit set to . This option is parsed by the color module and defaults to black without transparency. Default values are: or .
[Boolean] Do not enlarge if the width or height exceeds the specified dimensions. Default value:

Manipulate

Manipulate parameter options are detailed in the following table:

Manipulate optionDescription
[Boolean] Convert to 8-bit greyscale; 256 shades of grey. Default:
[Int|Float] (0.3 - 1000) Value representing the sigma of the Gaussian mask, where
[String|Object] Default: or

Sending the upload to a server

To store an upload, you must first upload a physical file directly to S3. When you do it successfully, you will receive a URL to the actual file - you need to store this URL in the property.

Fetching an upload from a server

To fetch the URL of the uploaded image, use the argument to generate the signature needed to access the private file. The signature automatically expires after the number of seconds you specify. Please note that you cannot access the URL when you fetch all properties at once using in your GraphQL query. This is because the URL is generated on the fly inside the method.