Uploading Files From URL
With Uploadcare, you can upload files from URLs and check their upload statuses via
Such requests return a JSON dictionary with a token that can be further used to check upload statuses for your files. Note, those tokens are not file UUIDs and cannot be used to directly address files. The actual file UUIDs are returned by the
Defines a target project your uploads will go to, by its public key. If
pub_key is missing, method returns an error,
[HTTP 400] pub_key is required.
Defines your source file URL, which should be a public HTTP or HTTPS link. If
source_url is missing, method returns an error,
[HTTP 400] source_url is required.
Sets the file storing behavior. Once stored, files are not deleted after a 24-hour period. Accepted values are:
0or not set — files do not get stored upon uploading.
1— files get stored upon uploading. Requires the “automatic file storing” setting to be enabled.
auto— file storing works in line with your project settings.
(Optional) Sets the name for a file uploaded from URL. If not defined, the filename is obtained from either response headers or a source URL.
You can upload some files via
/from_url/ more than once. To handle such iterative cases, we implemented Recurrent Uploads, a mechanism saving URLs that have already been used with
/from_url/. When you start getting data from such a URL, you are immediately returned an existing UUID along with related data from your project without having to wait for an actual download. That saves your time and traffic.
Recurrent Uploads operate within a scope of your Uploadcare project identified by its public key. Below, we call URLs that are encountered more than once “URL duplicates.”
To activate the Recurrent Uploads feature, use the following two parameters with
/from_url/ to alter its behavior.
Checking for URL duplicates,
Runs the duplicate check and provides the immediate-download behavior.
0or not set, run no duplicate checks, execute the download anyway.
1, check if a
source_urlwas used before with the
save_URL_duplicatesparameter set to
1. If the URL was saved previously, no download happens.
Note, once you enable the parameter,
save_URL_duplicates gets triggered with the same value.
Saving new URLs for further recurrent uploads,
Provides the save/update URL behavior. The parameter can be used if you believe a
source_url will be used more than once. Using the parameter also updates an existing reference with a new
If you don’t explicitly define
save_URL_duplicates, it is by default set to the value of
0, saves no URL duplicates.
1, save the
source_urlor update an existing item.
/from_url/ response structure depends on the
type field of response JSON. If
token response JSON will look like this:
file_info response JSON will look like this:
"original_filename": "LED bulb.jpg",
Here is a basic example of how you upload a file from URL with Uploadcare,
Note, once you get a file token, use the
/status/ method to recieve an actual file UUID.
source_url is provided, e.g. not a URL,
[HTTP 400] Failed to parse URL.
source_url URL scheme info, like
http://, is missing,
[HTTP 400] No URL scheme supplied.
Currently, we only support uploading from
https:// resources, otherwise you get an error,
[HTTP 400] Invalid URL scheme.
source_url does not exist, e.g. resource is gone,
[HTTP 400] Host does not exist.
If your provided
source_url is in our blacklist,
[HTTP 400] Source is blacklisted.
source_url contains a malformed host,
[HTTP 400] URL host is malformed.
source_url refers to a private IP, e.g.
[HTTP 400] Only public IPs are allowed.
This method handles file tokens you get when using the
Sets a token returned by the
/from_url/ method. If the token is missing,
/status/ returns an error,
[HTTP 400] token is required.
If everything is ok,
/status/ returns a JSON dictionary holding an upload status and additional info. Here is a list of possible upload statuses,
- progress, upload is in progress. You also get the additional
donefields holding file size in bytes.
null, e.g. when an origin server does not provide the needed info.
string, if your uploading from URL returns an error, the respective field contains its short description.
- success, everything went smoothly. You also get all the file info fields.
The following example deals with the
error upload status and shows a short description for it,
"error": "FileTooBig: 1150844928 > 104857600"
Otherwise, when everything is ok, you get the
success uploading status and a bunch of other field related to file info,