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.

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
  }
}