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,

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:

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


// adding a simple filename

// using a char allowed in the pchar definition

// allowed in pchar together with Image Transformations

// using a sub-delim allowed in pchar together with Image Transformations

// using percent-encoded gen-delims that are not allowed in pchar


// using gen-delims that are not allowed in pchar without encoding[desaturated]@2x.jpg

Image Transformations

You can also process any file on the CDN using our Image Transformations. This requires including proper URL directives in your CDN URLs using /-/ as a separator. Each operation has its name and arguments, which are separated by forward slashes, /. Here, take a look at the example,

In the example, we just invoked the two Image Transformations: resize with the argument 200x and rotate with the argument 90.

As mentioned, you can complete a URL holding processing operations with an RFC3986 compliant filename.

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

Authenticated URLs

You can control who and when have access to files uploaded to your account. The functionality is provided by the Uploadcare feature called Authenticated URLs. When enabled, a user will require a token to access your content.

Token authentication also ensures a URL can only be accessed within a defined time span. Once a token expires, the content will no longer be accessible. To re-access the content, a new URL should be generated.

The Authenticated URLs feature may be useful when:

  • Your users upload personal, medical or other sensitive data.
  • You want your content to be rendered by authorized users only.
  • You want users to access your content only within a specified time frame.

Authenticated URLs work together with custom domains; you should set up a custom CNAME before using the feature. The format of an authenticated URL depends on a CDN provider your custom domain is connected to. We are currently working with Akamai and KeyCDN.

This is how authenticated URLs look like:




  • is your custom CNAME.
  • {uuid} is a unique file identifier or UUID.
  • {token} is a generated token used to access your content using a authenticated URL.
  • {timestamp} is an expiry date provided with the access token.

Note, {timestamp} must be defined as the Unix time when a provided token is set to expire.

Access tokens are generated on your backend. There is plenty of ready-made solutions for popular languages:

  • For Akamai (C, C#, Erlang, Go, Java, Perl, PHP, Python, Ruby)
  • For KeyCDN (PHP, Python, Ruby, NodeJS, Java)

Drop us a line in case you want to enable the Authenticated URLs feature for your account.