Handling File Groups

Groups serve a purpose of better organizing files in your Uploadcare projects. You can create one from a set of files by using their UUIDs.

Note, Image Transformations are not stripped off but stored in a group together with file UUIDs.

Making a group

POST /group/

Such requests return a JSON or JSONP response with your group info.

Query parameters

pub_key, `string`

Defines a target project you work with, by its public key. If pub_key is missing, method returns an error:

[HTTP 400] pub_key is required.

files[n]

That parameter defines a set of files you want to join in a group. Technically, it should be a set of ordered parameters where can either be n a unique positive number or zero. Each parameter can be a file UUID or a CDN URL, with or without applied Image Transformations operations. If the parameter is missing or empty, method returns an error:

[HTTP 400] no files[N] parameters found.

If any of the files you provide is represented with an invalid UUID or CDN URL, the method returns an error:

[HTTP 400] this is not valid file url: http://invalid/url.

If some of the files you provide are missing in the project defined by your pub_key, then method returns an error:

[HTTP 400] some files not found.

callback

Sets the name of your JSONP callback function.

Making a group, example

Below is the example of joining two files in a group: one by UUID and another with its Image Transformations.

Request:

curl -F "pub_key=demopublickey" \
     -F "files[0]=d6d34fa9-addd-472c-868d-2e5c105f9fcd" \
     -F "files[1]=b1026315-8116-4632-8364-607e64fca723/-/resize/x800/" \
     "https://upload.uploadcare.com/group/"

Response:

{
  "id": "6e5e2226-d4a6-459b-824d-ff5f8090eaf9~2",
  "datetime_created": "2014-07-18T13:29:20.272Z",
  "datetime_stored": null,
  "files_count": 2,
  "cdn_url": "http://www.ucarecdn.com/6e5e2226-d4a6-459b-824d-ff5f8090eaf9~2/",
  "url": "https://api.uploadcare.com/groups/6e5e2226-d4a6-459b-824d-ff5f8090eaf9~2/",
  "files": [
    {
      "default_effects": "",
      "is_stored": true,
      "uuid": "d6d34fa9-addd-472c-868d-2e5c105f9fcd",
      "is_image": true,
      "is_ready": true,
      ...
    },
    {
      "default_effects": "resize/x800/",
      "is_stored": true,
      "uuid": "b1026315-8116-4632-8364-607e64fca723",
      "is_image": true,
      "is_ready": true,
      ...
    }
  ]
}