Accessing Files via REST API

The File Resource is intended to handle user-uploaded files and is the main Uploadcare resource.

Each of uploaded files has a UUID that is assigned once and never changes later. That means it is safe to store file UUIDs in your database or even your Moleskine. Here is a complete list of file properties,

File properties

Property	Type	Value
`datetime_removed`	string or null	Date and time when a file was removed, if any.
`datetime_stored`	string or null	Date and time of the last store request, if any.
`datetime_uploaded`	string	Date and time when a file was uploaded.
`is_image`	boolean	`true`, if your file is an image and can be processed via Image Processing, Please note, our processing engine does not treat all image files as such. Some of those may not be supported due to file sizes, resolutions or formats. In the case, the flag is set to false. `false` otherwise.
`is_ready`	boolean	If a file is ready and not deleted, it is available on CDN.
`mime_type`	string	File MIME type.
`original_file_url`	string or null	Publicly available file CDN URL. Available if a file is not deleted.
`original_filename`	string	Original name of an uploaded file.
`filename`	string	Sanitized name of an uploaded file. Valid symbols are: `a-zA-Z0-9._`. In case all symbols are removed, `filename` becomes `noroot.%ext%` or `noroot`.
`size`	number	File size in bytes.
`url`	string	API resource URL for a particular file.
`uuid`	string	File UUID.
`image_info`	object	Image meta (if a file is an image): Width and height Orientation Geolocation, from EXIF Original datetime, from EXIF Format Resolution, DPI

Getting a paginated list of files

Before accessing individual files, you might first want to get a complete paginated file list. Here’s how:

GET /files/

You MAY also include the following optional parameters in your query,

removed, `boolean`

true to only include removed files in the response, false to include existing files. Defaults to false.

stored, `boolean`

true to only include files that were stored, false to include temporary ones. The default is unset: both stored and not stored files are returned.

limit, `number`

A preferred amount of files in a list for a single response. Defaults to 100, while the maximum is 1000.

ordering

Specifies the way files are sorted in a returned list,

datetime_uploaded — by upload time, ascending order.
-datetime_uploaded — by upload time, descending order.
size - by file size, ascending order.
-size - by file size, descending order.

The default ordering option is datetime_uploaded.

from

A starting point for filtering files. The value depends on your ordering parameter value.

If ordering=datetime_uploaded then a datetime MUST be used, YYYY-MM-DDTHH:MM:SS, where T is used as a separator. Example:

?ordering=-datetime_uploaded&from=2015-09-10T10:00:00

If ordering=size then an integer file size MUST be used. File sizes SHOULD be set in bytes. Example:

?ordering=size&from=12909

Example, getting a file list

Request:

curl -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     "https://api.uploadcare.com/files/?stored=true&limit=10&from=5000&ordering=-size"

Response:

{
  "next": "https://api.uploadcare.com/files/?from=3100&ordering=-size&stored=true&limit=10&offset=0",
  "previous": null,
  "total": 1893,
  "per_page": 10,
  "results": [
    {
      "original_file_url": "http://www.ucarecdn.com/017162da-e83b-46fc-89fc-3a7740db0a82/mango.jpg",
      "image_info": {
        "height": 510,
        "width": 910,
        "geo_location": null,
        "datetime_original": null,
        "format": "JPEG"
      },
      "mime_type": "image/jpg",
      "is_ready": true,
      "url": "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/",
      "uuid": "017162da-e83b-46fc-89fc-3a7740db0a82",
      "original_filename": "mango.jpg",
      "datetime_uploaded": "2021-01-09T16:31:08.216Z",
      "size": 390340,
      "is_image": true,
      "datetime_stored": "2021-02-03T13:10:04.430Z",
      "datetime_removed": null,
      "source": null
    },
    ...
  ]
}

Copying uploaded files to a specified storage

POST /files/

POST requests are used to copy original files or their modified versions to a custom storage or the default one. Source files MAY either be stored or just uploaded and MUST NOT be deleted.

Parameters you MAY include:
- source, points to a file subjected to copy.
- target, points to a target custom storage.
- store, switching the file storing option.
- make_public, make files on custom storage available via public links.
- pattern, define file naming pattern for the custom storage scenario.
Examples
- More on POST responses
- POST Request-Response example
Limits
Possible errors

The following parameters MAY be included in POST requests,

source, `string` , required

A CDN URL or just UUID of a file subjected to copy. For example:

http://www.ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/resize/200x/roof.jpg

85b5644f-e692-4855-9db0-8c5a83096e25

If source is invalid, the method returns an error:

{"detail": "Bad `source` parameter. Use UUID or CDN URL."}

If source is missing, the method returns an error:

{"detail": "`source` parameter is required."}

target, `string` , optional

Identifies a custom storage name related to your project. Implies you are copying a file to a specified custom storage. Keep in mind you can have multiple storages associated with a single S3 bucket.

If target is invalid, the method returns an error:

{"detail": "Project has no storage with provided name."}

store, `boolean` , optional

The parameter only applies to the Uploadcare storage and MUST be either true or false.

true to store files while copying. If stored, files won’t be automatically deleted after a 24-hour period. false to not store files, default.

In case the provided value is invalid, the method returns an error:

{"detail": "`store` parameter should be `true` or `false`."}

make_public, `boolean` , optional

Applicable to custom storage only. MUST be either true or false. true to make copied files available via public links, false to reverse the behavior.

If not specified, the default value is true.

Some settings of the target bucket can prohibit adding new objects with public access. If you make the copied files public, make sure the "Block public access to buckets and objects granted through new access control lists (ACLs)" option is turned off in bucket settings.

In case the provided value is invalid, the method returns an error:

{"detail": "`make_public` parameter should be `true` or `false`."}

pattern, optional

Applies to custom storage usage scenario only. The parameter is used to specify file names Uploadcare passes to a custom storage. In case the parameter is omitted, we use pattern of your custom storage.

Allowed values:

${default} = ${uuid}/${auto_filename}
${auto_filename} = ${filename} ${effects} ${ext}
${effects} = processing operations put into a CDN URL
${filename} = original filename, no extension
${uuid} = file UUID
${ext} = file extension, leading dot, e.g. .jpg

In case of an invalid value, an error is returned:

{"detail": "Invalid pattern provided: `pattern_value`"}

In case of an invalid symbol found in a pattern:

{"detail": "Invalid pattern provided: Invalid character in a pattern."}

Response example, POST

POST requests return a JSON dictionary containing the type and result fields. For the url type, the result is a URL with the s3 scheme. Your bucket name is put as a host, and an s3 object path follows. For example:

s3://my-bucket/85b5644f-e692-4855-9db0-8c5a83096e25/roof.resize_200x.jpeg

Copying is synchronous: new files can be used upon a request completion. Hence, copy requests take more time for large files. Here are some examples,

Request examples, POST

The example below copies a file to an Uploadcare project identified by a key pair. source is used, and the resulting file gets stored and will be available outside of the 24-hour period.

Request:

curl -X POST \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -d "source=017162da-e83b-46fc-89fc-3a7740db0a82" \
     -d "store=true" \
     "https://api.uploadcare.com/files/"

Response:

{
  "type": "file",
  "result": {
    "original_file_url": "http://www.ucarecdn.com/d1d2dc43-4904-4783-bb4d-fbcf64264e63/mango.jpg",
    "image_info": {
      "height": 510,
      "width": 910,
      "geo_location": null,
      "datetime_original": null,
      "format": "JPEG"
    },
    "mime_type": "image/jpg",
    "is_ready": true,
    "url": "https://api.uploadcare.com/files/d1d2dc43-4904-4783-bb4d-fbcf64264e63/",
    "uuid": "d1d2dc43-4904-4783-bb4d-fbcf64264e63",
    "original_filename": "mango.jpg",
    "datetime_uploaded": "2021-02-03T13:10:04.430Z",
    "size": 0,
    "is_image": null,
    "datetime_stored": "2021-02-03T13:10:04.430Z",
    "datetime_removed": null,
    "source": "/017162da-e83b-46fc-89fc-3a7740db0a82/"
  }
}

Here, we are copying a file to a custom storage named mytarget and related to a project identified by the provided key pair. Note, since your storage and bucket names can be different, the S3 link in the response below refers to mybucket rather than mytarget.

Request:

curl -X POST \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -d "source=017162da-e83b-46fc-89fc-3a7740db0a82" \
     -d "target=mytarget" \
     "https://api.uploadcare.com/files/"

Response:

{
    "type": "url",
    "result": "s3://mybucket/017162da-e83b-46fc-89fc-3a7740db0a82/mango.jpg"
}

The next example covers a case where you are using Uploadcare as a buffer to created processed file versions and then put those to the custom storage named mytarget. Since no pattern is specified, the default one is used, ${uuid}/${auto_filename}.

Request:

curl -X POST \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -d "source=017162da-e83b-46fc-89fc-3a7740db0a82/-/resize/20x/" \
     -d "target=mytarget" \
     "https://api.uploadcare.com/files/"

Response:

{
  "type": "url",
  "result": "s3://mybucket/017162da-e83b-46fc-89fc-3a7740db0a82/image.resize_20x.png"
}

Limits, POST

Here goes the list of limits that apply when copying files via REST API:

If file CDN URLs include Image Transformations, their sizes MUST NOT exceed 100 MB.
In case Image Transformations are not included in CDN URLs, file sizes MUST NOT exceed 5 GB.
If a source file is copied to a target custom bucket, its size MUST NOT exceed 5 GB.

Possible errors, POST

All of the listed errors are returned with the HTTP 400 Bad Request status code.

When a file is not yet uploaded:

{"detail": "File is not ready yet."}

When trying to copy a file that is too large:

{"detail": "Copying of large files is not supported at the moment."}

If your current does not cover a requested feature:

{"detail": "Not allowed on your current plan."}

Batch file storing

PUT requests are used to store multiple files in one go:

PUT /files/storage/

Up to 100 files are supported per request. A JSON object holding your File list SHOULD be put into a request body.

Request example, PUT

In the example below, we make a request to store two files passed into the request body as a JSON. In the example response, the files are marked as is_ready and have datetime_stored.

Request:

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -d '["21975c81-7f57-4c7a-aef9-acfe28779f78",
          "cbaf2d73-5169-4b2b-a543-496cf2813dff"]' \
     "https://api.uploadcare.com/files/storage/"

Response:

{
  "status":"ok",
  "problems":{},
  "result":[
    {
      "uuid":"21975c81-7f57-4c7a-aef9-acfe28779f78",
      "original_file_url":"http://www.ucarecdn.com/21975c81-7f57-4c7a-aef9-acfe28779f78/image28MB.jpg",
      "image_info":{
          "orientation":null,
          "format":"JPEG",
          "height":1200,
          "width":1920,
          "geo_location":null,
          "datetime_original":null
      },
      "mime_type":"image/jpeg",
      "is_ready":true,
      "url":"https://api.uploadcare.com/files/21975c81-7f57-4c7a-aef9-acfe28779f78/",
      "original_filename":"image2.8MB.jpg",
      "datetime_uploaded":"2015-1209T03:47:24.952489Z",
      "size":2863008,
      "is_image":true,
      "datetime_stored":"2015-12-09T03:47:24.971880Z",
      "datetime_removed":null,
      "source":null
    },
    {
      "uuid":"cbaf2d73-5169-4b2b-a543-496cf2813dff",
      ...
    }
  ]
}

In case file list provided in a request holds invalid UUIDs, they will be included in the problems structure. Invalid UUIDs can be incomplete, associated with files that no longer exist, etc.

{
  "status": "ok",
  "problems": {
    "21975c81-7f57-4c7a-aef9-acfe28779f78": "Missing in the project",
    "4j334o01-8bs3": "Invalid"
  },
  "result":[
    {
      "uuid": "cbaf2d73-5169-4b2b-a543-496cf2813dff",
      ...
    }
  ]
}

Batch file delete, DELETE

A commonly used operation of deleting many files at once expects input similar to PUT store requests: a list of UUIDs in a JSON. Supports up to 100 UUIDs per request.

DELETE /files/storage/

Possible errors when handling multiple files

Sent data is not a list

{"detail": "Expected list of UUIDs"}

Sent data is an empty list

{"detail": "List of UUIDs can not be empty"}

A count of sent UUIDs exceeds the limit

{"detail": "Maximum UUIDs per request is exceeded. The limit is 100"}

Getting info for a single file by UUID

Once you obtain a list of files, you might want to acquire some file-specific info. It is also done using the GET verb:

GET /files/:uuid/

Request example, GET

The example is about getting a response object for a single file by its UUID.

Request:

curl -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/"

Response:

{
  "original_file_url": "http://www.ucarecdn.com/017162da-e83b-46fc-89fc-3a7740db0a82/mango.jpg",
  "image_info": {
    "height": 510,
    "width": 910,
    "geo_location": null,
    "datetime_original": null,
    "format": "JPEG"
  },
  "mime_type": "image/jpg",
  "is_ready": true,
  "url": "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/",
  "uuid": "017162da-e83b-46fc-89fc-3a7740db0a82",
  "original_filename": "mango.jpg",
  "datetime_uploaded": "2021-01-09T16:31:08.216Z",
  "size": 390340,
  "is_image": true,
  "datetime_stored": "2021-02-03T13:10:04.430Z",
  "datetime_removed": null,
  "source": null
}

Delete a single file by UUID

Beside deleting in a multi-file mode, you can remove individual files.

DELETE /files/:uuid/storage/

DELETE /files/:uuid/

Request example, DELETE

The first example deals with the /files/:uuid/storage/ request version,

Request:

curl -I -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -X DELETE \
     "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/storage/"

Response:

HTTP/1.1 302 FOUND
Access-Control-Allow-Headers: Authorization
Access-Control-Allow-Origin: https://uploadcare.com
Allow: GET, POST, PUT, DELETE, OPTIONS, PATCH
Content-Type: text/html; charset=utf-8
Date: Tue, 9 Feb 2021 21:00:51 GMT
Location: https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/
Content-Length: 0

...

The second example refers to the /files/:uuid/ request version.

Request:

curl -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -X DELETE \
     "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/"

Response:

{
  "original_file_url": "http://www.ucarecdn.com/017162da-e83b-46fc-89fc-3a7740db0a82/mango.jpg",
  "image_info": {
    "height": 510,
    "width": 910,
    "geo_location": null,
    "datetime_original": null,
    "format": "JPEG"
  },
  "mime_type": "image/jpg",
  "is_ready": true,
  "url": "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/",
  "uuid": "017162da-e83b-46fc-89fc-3a7740db0a82",
  "original_filename": "mango.jpg",
  "datetime_uploaded": "2021-01-09T16:31:08.216Z",
  "size": 390340,
  "is_image": true,
  "datetime_stored": null,
  "datetime_removed": "2021-02-03T13:10:04.430Z",
  "source": null
}

Store a single file by UUID

Once stored, a file is then available outside of the 24-hour period until it gets removed.

PUT /files/:uuid/storage/

The following example deals with storing a single file by using its UUID. Note, once stored, the file is marked with is_ready and has a datetime_stored stamp.

Request:

curl -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -X PUT \
     "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/storage/"

Response:

{
  "original_file_url": "http://www.ucarecdn.com/017162da-e83b-46fc-89fc-3a7740db0a82/mango.jpg",
  "image_info": {
    "height": 510,
    "width": 910,
    "geo_location": null,
    "datetime_original": null,
    "format": "JPEG"
  },
  "mime_type": "image/jpg",
  "is_ready": true,
  "url": "https://api.uploadcare.com/files/017162da-e83b-46fc-89fc-3a7740db0a82/",
  "uuid": "017162da-e83b-46fc-89fc-3a7740db0a82",
  "original_filename": "mango.jpg",
  "datetime_uploaded": "2021-01-09T16:31:08.216Z",
  "size": 390340,
  "is_image": true,
  "datetime_stored": "2021-02-03T13:10:04.430Z",
  "datetime_removed": null,
  "source": null
}

Accessing Files via REST API

File properties

Getting a paginated list of files

removed, boolean

stored, boolean

limit, number

ordering

from

Example, getting a file list

Copying uploaded files to a specified storage

source, string , required

target, string , optional

store, boolean , optional

make_public, boolean , optional

pattern, optional

Response example, POST

Request examples, POST

Limits, POST

Possible errors, POST

When a file is not yet uploaded:

When trying to copy a file that is too large:

If your current does not cover a requested feature:

Batch file storing

Request example, PUT

Batch file delete, DELETE

Possible errors when handling multiple files

Sent data is not a list

Sent data is an empty list

A count of sent UUIDs exceeds the limit

Getting info for a single file by UUID

Request example, GET

Delete a single file by UUID

Request example, DELETE

Store a single file by UUID

removed, `boolean`

stored, `boolean`

limit, `number`

source, `string` , required

target, `string` , optional

store, `boolean` , optional

make_public, `boolean` , optional