Accessing Files via REST API
The File Resource is intended to handle user-uploaded files and is the main Uploadcare resource.
- File properties
- Getting a paginated list of files, GET
- Copying uploaded files to a specified storage, POST
- Batch file storing, PUT
- Batch file delete, DELETE
- Getting info for a single file by UUID, GET
- Delete a single file by UUID, DELETE
- Store a single file by UUID, PUT
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 |
---|---|---|
| string or null | Date and time when a file was removed, if any. |
| string or null | Date and time of the last store request, if any. |
| string | Date and time when a file was uploaded. |
| boolean |
|
| boolean | If a file is ready and not deleted, it is available on CDN. |
| string | File MIME type. |
| string or null | Publicly available file CDN URL. Available if a file is not deleted. |
| string | Original name of an uploaded file. |
| string | Sanitized name of an uploaded file. Valid symbols are:
|
| number | File size in bytes. |
| string | API resource URL for a particular file. |
| string | File UUID. |
| 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/
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
- 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 atarget
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/
or
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
}