Docs

Uploading Files From URL

With Uploadcare, you can upload files from URLs and check their upload statuses via GET requests,

GET /from_url/

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 /status/ endpoint.

Request parameters

pub_key, string

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.

source_url

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.

store

Sets the file storing behavior. Once stored, files are not deleted after a 24-hour period. Accepted values are:

  • 0 or 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.

filename

(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.

Recurrent Uploads

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, check_URL_duplicates

Runs the duplicate check and provides the immediate-download behavior.

  • 0 or not set, run no duplicate checks, execute the download anyway.
  • 1, check if a source_url was used before with the save_URL_duplicates parameter 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, save_URL_duplicates

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 source_url content.

If you don’t explicitly define save_URL_duplicates, it is by default set to the value of check_URL_duplicates.

  • 0, saves no URL duplicates.
  • 1, save the source_url or update an existing item.

Return values

/from_url/ response structure depends on the type field of response JSON. If type is token response JSON will look like this:

{
  "type": "token",
  "token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}

If type is file_info response JSON will look like this:

{
  "type": "file_info",
  "size": 381192,
  "total": 381192,
  "done": 381192,
  "uuid": "3d61c352-b22f-4487-9c8f-33384f5898ae",
  "file_id": "3d61c352-b22f-4487-9c8f-33384f5898ae",
  "filename": "LEDbulb.jpg",
  "original_filename": "LED bulb.jpg",
  "is_image": true,
  "is_stored": true,
  "image_info": {
    "height": 2352,
    "width": 2935,
    "geo_location": null,
    "datetime_original": null,
    "format": "JPEG"
  },
  "video_info": {},
  "is_ready": true,
  "mime_type": "image/jpeg"
}

Example

Here is a basic example of how you upload a file from URL with Uploadcare,

Request:

curl "https://upload.uploadcare.com/from_url/\
?pub_key=demopublickey&store=1\
&source_url=http%3A%2F%2Fabs.twimg.com%2Fb%2Ffront_page%2Fv1%2FEU_4.jpg"

Response:

{
  "token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}

Note, once you get a file token, use the /status/ method to recieve an actual file UUID.

Errors

If incorrect source_url is provided, e.g. not a URL,

[HTTP 400] Failed to parse URL.

If source_url URL scheme info, like http://, is missing,

[HTTP 400] No URL scheme supplied.

Currently, we only support uploading from http:// or https:// resources, otherwise you get an error,

[HTTP 400] Invalid URL scheme.

If 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.

If source_url contains a malformed host,

[HTTP 400] URL host is malformed.

If provided source_url refers to a private IP, e.g. 192.168.0.1,

[HTTP 400] Only public IPs are allowed.

Checking upload status and working with file tokens

This method handles file tokens you get when using the /from_url/ method.

GET /from_url/status/

Request parameters

token, string

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 total and done fields holding file size in bytes. total can be null, e.g. when an origin server does not provide the needed info.
  • error, 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.

Examples

The following example deals with the error upload status and shows a short description for it,

Request:

curl "https://upload.uploadcare.com/from_url/status/\
?token=3ef5d533-68fb-4039-8cd2-41a4d045db0a"

Response:

{
  "status": "error",
  "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,

Request:

curl "https://upload.uploadcare.com/from_url/status/\
?token=945ebb27-1fd6-46c6-a859-b9893712d650"

Response:

{
  "status": "success",
  "is_stored": true,
  "done": 145212,
  "file_id": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
  "total": 145212,
  "size": 145212,
  "uuid": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
  "is_image": true,
  "filename": "EU_4.jpg",
  "is_ready": true,
  "original_filename": "EU_4.jpg",
  "mime_type": "image/jpeg",
  "image_info": {
    "orientation": null,
    "format": "JPEG",
    "height": 640,
    "width": 960,
    "geo_location": null,
    "datetime_original": null
  }
}