File group operations

File groups serve as collections of files that help you organize content within your Uploadcare project. Most often, groups of files are used in multipage document conversion and creating video thumbnails. The files after applying these operations are marked as a group and you can access them.

You can access file group via :group_uuid:

https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/
https://ucarecdn.com/:group_uuid/

:group_uuid is similar to a single file UUID but contains the file number ~N at the end.

A group URL refers to a page listing individual file URLs with their UUIDs and index numbers in that group.

File group limitations:

  • File groups can contain up to 1000 files.
  • File groups are immutable; adding, deleting or changing group elements is impossible.
  • A group itself and files within it MUST belong to the same project.

Creating file groups

One of the other typical use cases is creating a file group when a user uploads multiple files simultaneously and then wants to display them together.

You can create a group of already uploaded files:

$curl -L 'https://upload.uploadcare.com/group/' \
>     -F 'pub_key="$YOUR_PUBLIC_KEY"' \
>     -F 'files[0]=":uuid1"' \
>     -F 'files[1]=":uuid2/-/scale_crop/400x600/"' \
>     -F 'files[2]=":uuid3"'

Get $YOUR_PUBLIC_KEY from API keys.

Check out our API refs for creating and managing groups.

Creating file groups via File Uploader

When uploading multiple files via a File Uploader, you can group them and assign them the same URL. This option is turned off by default. When it’s turned on, it stores UUIDs of uploaded files. In this case, a separate URL is also generated for each file.

Getting file group information

You can get information about a file group:

$curl -L 'https://upload.uploadcare.com/group/info/?pub_key=$YOUR_PUBLIC_KEY&group_id=group_uuid'

Returns a JSON object with information about a file group (when the group was created, number of the files in the group, etc).

Accessing a single file in a group

Requesting a specific file in a group is achieved by adding /nth/i/, where i is a file index, starting from 0:

https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/nth/0/
/:group_uuid/nth/0/
https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/nth/1/
/:group_uuid/nth/1/
https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/nth/2/
/:group_uuid/nth/2/

Note, there is no /-/ separator after a group UUID. It’s required for image processing operations only.

Applying image processing operations

Image processing operations cannot be applied to a file group URL.

You can group several files with image processing operations already applied. In this case, the transform file can be requested directly as a group element (/nth/N/).

https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/nth/1/
/:group_uuid/nth/1/

Adding additional processing operations after /-/ will apply them on top of the existing ones. You can apply image processing operations to individual files within a group:

https://ucarecdn.com/cd334b26-c641-4393-bcce-b5041546430d~11/nth/1/-/resize/256x/
/:group_uuid/nth/1/-/resize/256x/

Getting a group as an archive

Getting a group as an archive is done via the archive group processing operation.

The operation limits are:

  • A total size of uncompressed files ≤ 2 GB.
  • Processing operations will be discarded.
    Only original files will be archived.
    Note: If you add an image with a transformation to a group, then only the original images will be loaded when exporting the archive of this group.

Here’s how to get an archived file group:

/:group_uuid/archive/:format/:filename

Where:

  • :group_uuid — UUID of a file group you want to get as an archive.
  • :format — the format of that output archive, we support zip and tar.
  • :filename (optional) — output archive filename.

Note: If the group contains a removed file, the archive operation will fail with a 404 error code.

Deleting groups

Deleting a file group using the REST API deletes only the group object itself. All files included in the group will remain intact.

You can delete a group:

curl -X DELETE \
     -H 'Content-Type: application/json' \
     -H "Accept: application/vnd.uploadcare-v0.7+json" \
     -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
     "https://api.uploadcare.com/groups/:group_uuid/"

Get $YOUR_PUBLIC_KEY and $YOUR_SECRET_KEY from API keys.

Note: Cleaning the CDN cache may take some time after deletion.

For more information on managing file groups, refer to the REST API references.