Accessing File Groups via REST API

Individual files on Uploadcare can be joined into groups. Those can be used to better organize your workflow. Technically, groups are ordered lists of files and can hold files together with Image Transformations in their URLs. The most common case with creating groups is when users upload multiple files at once.

Note, a group itself and files within that group MUST belong to the same project. Groups are immutable and the only way to add/remove a file is creating a new group.

Group identifiers
Group properties
Get a paginated list of groups, GET
- Request parameters
Get a file group by UUID, GET
Store all files in a group, PUT

Group identifiers

Groups are identified in a way similar to individual files. A group ID consists of a UUID followed by a “~” tilde character and a group size: integer number of files in group. For example, here is an identifier for a group holding 12 files,

badfc9f7-f88f-4921-9cc0-22e2c08aa2da~12

Group properties

Property	Type	Value
`datetime_created`	string	Date and time when a group was created.
`datetime_stored`	string	Date and time when files in a group were stored.
`files_count`	number	Number of files in a group.
`cdn_url`	string	Public CDN URL for a group.
`files`	array	List of files in a group. Deleted files are represented as `null` to always preserve a number of files in a group in line with a group ID. This property is not available for group lists.
`url`	string	API resource URL for a group.
`id`	string	Group identifier.

Get a paginated list of groups

Multiple groups can be present in your project. This means you might first want to access a list of those groups, then individual groups, and files.

GET /groups/

You MAY also include the following optional parameters in your query,

limit, `number`

A preferred amount of groups in a list for a single response. Defaults to 100, while the maximum is 1000.

from, `datetime`

A starting point for filtering group lists. MUST be a datetime value with T used as a separator,

?from=2015-01-02T10:00:00

ordering

Specifies the way groups are sorted in a returned list,

datetime_created - by creation time, ascending order.
-datetime_created - by creation time, descending order.

Defaults to datetime_created.

Get a file group by UUID

GET /groups/:group_id/

You may refer to getting a single file for a request and response example.

Mark all files in a group as stored

For your files to be available on from our CDN after the initial 24-hour period, you should store them. You can do that by either storing a file group, storing an individual file or storing a list of files.

PUT /groups/:group_id/storage/

You may refer to storing a single file for a request and response example.