Docs

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

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.