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