strapi/docs/3.0.0-beta.x/plugins/upload.md

Upload

Thanks to the plugin Upload, you can upload any kind of files on your server or externals providers such as AWS S3.

Endpoints

Method	Path	Description
GET	/upload/files	Get a list of files
GET	/upload/files/:id	Get a specific file
POST	/upload	Upload files
DELETE	/upload/files/:id	Delete a file

Upload files

To upload files into your application.

Parameters

• files: The file(s) to upload. The value(s) can be a Buffer or Stream.

Code example

<form>
  <!-- Can be multiple files -->
  <input type="file" name="files" />
  <input type="submit" value="Submit" />
</form>

<script type="text/javascript">
  const formElement = document.querySelector('form');

  formElement.addEventListener('submit', e => {
    e.preventDefault();

    const request = new XMLHttpRequest();

    request.open('POST', '/upload');

    request.send(new FormData(formElement));
  });
</script>

::: warning You have to send FormData in your request body :::

Upload files related to an entry

To upload files that will be liked to an specific entry.

Request parameters

• files: The file(s) to upload. The value(s) can be a Buffer or Stream.
• path (optional): The folder where the file(s) will be uploaded to (only supported on strapi-provider-upload-aws-s3).
• refId: The ID of the entry which the file(s) will be linked to.
• ref: The name of the model which the file(s) will be linked to (see more below).
• source (optional): The name of the plugin where the model is located.
• field: The field of the entry which the file(s) will be precisely linked to.

Examples

The Restaurant model attributes:

"attributes": {
  "name": {
    "type": "string"
  },
  "cover": {
    "model": "file",
    "via": "related",
    "plugin": "upload"
  }
}

Code

<form>
  <!-- Can be multiple files if you setup "collection" instead of "model" -->
  <input type="file" name="files" />
  <input type="text" name="ref" value="restaurant" />
  <input type="text" name="refId" value="5c126648c7415f0c0ef1bccd" />
  <input type="text" name="field" value="cover" />
  <input type="submit" value="Submit" />
</form>

<script type="text/javascript">
  const formElement = document.querySelector('form');

  formElement.addEventListener('submit', e => {
    e.preventDefault();

    const request = new XMLHttpRequest();

    request.open('POST', '/upload');

    request.send(new FormData(formElement));
  });
</script>

::: warning You have to send FormData in your request body :::

Upload file during entry creation

You can also add files during your entry creation.

Examples

The Restaurant model attributes:

"attributes": {
  "name": {
    "type": "string"
  },
  "cover": {
    "model": "file",
    "via": "related",
    "plugin": "upload"
  }
}

Code

<form>
  <!-- Can be multiple files if you setup "collection" instead of "model" -->
  <input type="text" name="name" />
  <input type="file" name="cover" />
  <input type="submit" value="Submit" />
</form>

<script type="text/javascript">
  const formElement = document.querySelector('form');

  formElement.addEventListener('submit', e => {
    e.preventDefault();

    const request = new XMLHttpRequest();

    const formData = new FormData();

    const formElements = formElement.elements;

    const data = {};

    for (let i = 0; i < formElements.length; i++) {
      const currentElement = formElements[i];
      if (!['submit', 'file'].includes(currentElement.type)) {
        data[currentElement.name] = currentElement.value;
      } else if (currentElement.type === 'file') {
        if (currentElement.files.length === 1) {
          const file = currentElement.files[0];
          formData.append(`files.${currentElement.name}`, file, file.name);
        } else {
          for (let i = 0; i < currentElement.files.length; i++) {
            const file = currentElement.files[i];

            formData.append(`files.${currentElement.name}`, file, file.name);
          }
        }
      }
    }

    formData.append('data', JSON.stringify(data));

    request.open('POST', `${HOST}/restaurants`);

    request.send(formData);
  });
</script>

You entry data have to be contained in a data key. You have to JSON.stringify your data object.

And for your files, they have to be prefixed by files. Example here with cover attribute files.cover.

::: note If you want to upload files for a group, you will have to specify the inidex of the item you wan to add the file. Example files.my_group_name[the_index].attribute_name :::

::: warning You have to send FormData in your request body :::

Models definition

Adding a file attribute to a model (or the model of another plugin) is like adding a new association.

In the first example below, you will be able to upload and attach one file to the avatar attribute.

Path — User.settings.json.

{
  "connection": "default",
  "attributes": {
    "pseudo": {
      "type": "string",
      "required": true
    },
    "email": {
      "type": "email",
      "required": true,
      "unique": true
    },
    "avatar": {
      "model": "file",
      "via": "related",
      "plugin": "upload"
    }
  }
}

In our second example, you can upload and attach multiple pictures to the restaurant.

Path — Restaurant.settings.json.

{
  "connection": "default",
  "attributes": {
    "name": {
      "type": "string",
      "required": true
    },
    "convers": {
      "collection": "file",
      "via": "related",
      "plugin": "upload"
    }
  }
}

Install providers

By default Strapi provides a local file upload system. You might want to upload your files on AWS S3 or another provider.

You can check all the available providers developed by the community on npmjs.org - Providers list

To install a new provider run:

$ npm install strapi-provider-upload-aws-s3@beta --save

::: note If the provider is not in the mono repo, you probably don't need @beta depending if the creator published it with this tag or not. :::

Then, visit http://localhost:1337/admin/plugins/upload/configurations/development on your web browser and configure the provider.

Create providers

If you want to create your own, make sure the name starts with strapi-provider-upload- (duplicating an existing one will be easier to create), modify the auth config object and customize the upload and delete functions.