CDN File API

File API is about accessing single files on Uploadcare CDN. All of the file URLs begin with the assigned UUIDs. That is the basic case, and such links will simply return the original file,

https://ucarecdn.com/:uuid/

CDN filenames

Your original filenames can still be accessed via our REST API. You make a request and receive a JSON response holding many file params including original_filename. However, you can decide to use any other filename; just put it after the trailing slash in your CDN URL, see :filename in the example:

https://ucarecdn.com/:uuid/:filename

:filename should be constructed as filename.ext and comply with the section 3.3 of RFC3986. Long story short, the symbols you use in a filename must conform to the pchar definition:

pchar = unreserved / pct-encoded / sub-delims / ":" / "@"

You can find the list of RFC3986 reserved characters here. Since we do not allow using /path/filename.ext, you can still use gen-delims without percent-encoding them, but such URLs can be unsafe to use with other services.

Here are some examples:

Safe:

// adding a simple filename
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/image.jpg

// using a char allowed in the pchar definition
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/image@2x.jpg

// allowed in pchar together with Media Processing operations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/resize/550x/image@1x.jpg

// using a sub-delim allowed in pchar together with Media Processing operations
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image_black&white@2x.jpg

// using percent-encoded gen-delims that are not allowed in pchar
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image%5Bdesaturated%5D@2x.jpg

Unsafe:

// using gen-delims that are not allowed in pchar without encoding
https://ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/preview/-/grayscale/image[desaturated]@2x.jpg

Media Processing

You can also process any file on the CDN using our Media Processing. This requires appending processing operations to your file URL using /-/ as a separator. Each operation has its name and arguments, which are separated by forward slashes, /. Here, take a look at the example,

https://ucarecdn.com/:uuid/-/resize/200x/-/rotate/90/

In the example, we just invoked the two image processing operations: resize with the argument 200x and rotate with the argument 90.

As mentioned, you can complete a URL holding processing operations with a filename of your preference.

Image processing operations are part of Uploadcare Media Processing.

Further, your files can be arranged in groups, which behavior is regulated by our Group API.

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.