Upload one or multiple files

POST /v4/files

API Permissions

FILE_UPLOAD

Query Parameters

Parameter Type Default Description
folder string / optional Specifies the directory to upload the file into. If it does not exist, it will be created
Example: /path/to/folder
resize optional Sets the maximum dimensions (width,height) of the image. If the image is larger, it will be resized upon upload
Example: resize=1000,800
postprocess string optional Enqueues postprocess actions (see Postprocess actions section below)
Example: postprocess=blurhash

You can upload files using 3 methods:

Method 1 - multipart/form-data request

This is the most common way to upload a file and allows easy integration in HTML forms. The file(s) should be attached to the file parameter. You can also pass metadata with the meta[file]={} parameter.

The metadata object has to match the structure of your container (can be seen in the response of Get file details API). Both default and custom metadata fields are supported as well as multi-language fields.

Try it out

curl --request POST \
  --url 'https://api.filerobot.com/fdocs/v4/files?folder=/api-demo' \
  --header 'content-type: multipart/form-data' \
  --header 'X-Filerobot-Key: fa5fe3303dd34e1da4810915c7c3fd6f' \
  --form file=@photo.jpg \
  --form 'meta[file]={"price":"500","title":{"de_DE":"Foto","en_US":"photo","fr_FR":"photo","it_IT":"foto"}}'

Method 2 - URL(s) of remotely hosted file(s)

Request body

The body consists of an array named files_urls which contains a list of files to be uploaded. Each element can contain the following parameters:

Parameter Type Default Description
url string required Specifies the url of the file to be uploaded
name string optional Defines the new filename. If not specified, the original filename will be kept
meta object {} optional Fills in metadata fields upon upload
product object {} optional Assigns a product reference upon upload (see Product reference section below)

The metadata object has to match the structure of your container (can be seen in the response of Get file details API). Both default and custom metadata fields are supported as well as multi-language fields.

Try it out

The file(s) will be downloaded from their source URL into the Filerobot store. Click on the API Explorer tab to test the API in live.

host: 'https://api.filerobot.com/fdocs' path: /v4/files method: POST parameters: folder: '/api-demo' variables: {} headers: Content-Type: 'application/json' X-Filerobot-Key: fa5fe3303dd34e1da4810915c7c3fd6f body: | { "files_urls": [ { "name": "new_filename.jpg", "url":"http://sample.li/boat.jpg", "meta":{"material":"wood","description":{"de_DE":"Boot","en_US":"boat","fr_FR":"bateau","it_IT":"barca"},"price":"79000"} } ] } theme: clouds-midnight axiosTimeout: 35000 maxContentLength: 150000 render: curl_tab: true

You can provide up to 20 URLs in a single request. Additional files will not be uploaded.

Method 3 - base64-encoded content

You can upload base64-encoded content into Filerobot.

Parameter Default Description
name required Specifies the file name after upload.
data required Base64-encoded file.
postactions required decode_base64 decodes the uploaded content after upload to store as file.
meta {} optional Fills in metadata fields upon upload
product {} optional Assigns a product reference upon upload (see Product reference section below)

The metadata object has to match the structure of your container (can be seen in the response of Get file details API). Both default and custom metadata fields are supported as well as multi-language fields.

Try it out

Copy-paste the cURL request in your Terminal or click on the API Explorer tab to see the API in action.

host: 'https://api.filerobot.com/fdocs' path: /v4/files method: POST variables: {} headers: X-Filerobot-Key: fa5fe3303dd34e1da4810915c7c3fd6f Content-Type: application/json body: | { "name": "demo-api/new_image_from_base64.png", "meta": {"title": {"de_DE": "Bild", "en_US": "image", "fr_FR": "image", "it_IT": "immagine" }}, "data": "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iOHlZyCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcQQLCCGYAExBAuIIVhADMECYggWEEOwgBiCBcT4fwvd8vhlstsNAAAAAElFTkSuQmCC", "postactions": "decode_base64" } theme: clouds-midnight axiosTimeout: 35000 maxContentLength: 150000 render: curl_tab: true

Response

{
  "status": "success",
  "file": {
    "uuid": "889caa34-8c13-50c7-adc7-ffb9e2c50001",
    "name": "boat.jpg",
    "size": {
      "bytes": 67450,
      "pretty": "65.87 KB"
    },
    "type": "image/jpeg",
    "url": {
      "public": "https://store.filerobot.com/fdocs/api-demo/boat.jpg",
      "permalink": "https://api.filerobot.com/fdocs/v4/get/889caa34-8c13-50c7-adc7-ffb9e2c50001",
      "cdn": "https://fdocs.filerobot.com/api-demo/boat.jpg?vh=c78308",
      "path": "/api-demo/boat.jpg"
    },
    "hash": {
      "sha1": "c7830848f6760785265553efdf529823c0dc6d3d",
      "blur_hash": null
    },
    "created_at": "2021-08-11T22:24:51Z",
    "modified_at": "2021-08-11T22:24:51Z",
    "overwrite": false,
    "folder": {
      "uuid": "7610923e-80d0-50e8-a2e4-c509be390158",
      "name": "/api-demo"
    },
    "info": {
      "img_type": "JPEG",
      "img_w": 1300,
      "img_h": 812
    },
    "meta": {
      "material": "wood",
      "title": {
        "de_DE": "Boot",
        "en_US": "boat",
        "fr_FR": "bateau",
        "it_IT": "barca"
      },
      "price": "79000"
    }
  },
  "info": {
    "version": 2.26,
    "trace": "l-eu-ms-xxxtest.elastic-uploader.airstore.scal3fl3x.com",
    "uniq_id": "ea7e30f4eafc401c8d5be8eac844d133",
    "project_uuid": "094dd930-ccd3-4945-a051-a55b484678a8",
    "company_uuid": "c543bc43-0000-1111-2222-b5293daf15f4",
    "uploaded_files": 1,
    "files_count": 1,
    "init_db": "atom014:105"
  }
}

Product reference

To assign a product reference to an asset upon upload, you need to provide the reference number in the product object in your request:

"product": {
    "ref": "H03423",
    "position": 1, // optional
}

To manipulate product references on existing assets, please see the Product API section.

Postprocess actions

parameter description
blurhash Generates a blurhash of the uploaded image (see Blurhash). Information is added to asset metadata
face-count Passes the uploaded image through a face-detection algorithm which adds the number if faces in the image to the asset metadata
invalidate Invalidates the CDN URLs using the uploaded file path. Useful when replacing existing assets with the same filename
transcode Enqueues a video transcoding task (see Video transcoding) for the uploaded video
whitespace-detect Detects the presence of excess uniform background or solid color background. Useful for flagging images which might require cropping. Information is added to asset metadata