Images endpoint

GET /images/v1/{folder_path}?page={page}&limit={limit}

Get the JSON representation of a list of "image sets" that are directly contained within a specific folder path (with pagination). Each image set represents multiple variants of a single image, rendered at different scales.

This endpoint is useful for scenarios where images cannot be directly linked to the context in which they will be used, but rather should be used as a group by convention. For example, all images that display a single product may be stored together in a folder whose name includes the product ID. A frontend component could then use this API to list these images and include them in a gallery on a product details page.

This API uses pagination parameters and response properties that are intentionally similar to the base query component.

Parameters

The component accepts the following (component namespaced) request parameters upon calling it:


Name	Type	Default value	Description
folder_path	string	(none)	The absolute path of the folder in the repository. An image folder path always starts with `/content/gallery`. Any number of path elements can be appended to the base endpoint URL to retrieve the representation for the corresponding image folder. Examples: - `/delivery/images/v1/content/gallery/channel-templates/referencespa/articles`
page	int	1	This parameter allows requesting a specific page, when the response is paginated. The first page should be requested with page=1.
pageSize	int	20	The number of items to include in a single page. The last page will have a number of items equal to or less than this number.
limit	int	0	The maximum number of pages for which links will be rendered in the `pages` property of the response object. The value zero is interpreted to mean that links to all pages should be rendered without limit. Note that this parameter has no effect on any other property of the response. For example, setting limit=1 is an acceptable value, and it will not affect the ability to set the page parameter to a value greater than 1.

Responses

Code: 404
Description: Indicates that the requested folder_path does not exist.

Code: 200
Description: A JSON object containing pagination parameters, plus a single page of image objects represented as an array, alphabetically-sorted by file name.

Response object properties

Property	Type	Description
items	array of Image Set	Actual data for the items contained in the current page of paginated results. Each item is an image set.
size	int	Number of items listed on the current page.
offset	int	The offset value which the result set should start from.
total	int	The total number of items available in the result set across all pages.
first	Page	First page of the paginator.
previous	Page	Previous page of the paginator.
current	Page	Current page of the paginator.
next	Page	Next page of the paginator.
last	Page	Last page of the paginator.
pages	array of Page	Currently listed pages on the paginator.

Page properties

Property	Type	Description
number	int	The 1-based index number of this Page object within the set of pages.
links.self.href	URL	The Images Endpoint URL that will produce output for this page.

Image set properties

Property	Type	Description
name	String	The filename of the image as uploaded to the Content SaaS image gallery.
description	String	An optional string provided by a content editor. Sometimes useful for alt text for accessibility.
contentType	String	Always 'xm:imageset'.
original	Image Variant	One of several image variants that may be available within this image set. The "original" variant is always available.
thumbnail	Image Variant	One of several image variants that may be available within this image set. The "thumbnail" variant is always available.
banner	Image Variant	One of several image variants that may be available within this image set.
small	Image Variant	One of several image variants that may be available within this image set.
large	Image Variant	One of several image variants that may be available within this image set.
smallsquare	Image Variant	One of several image variants that may be available within this image set.
mediumsquare	Image Variant	One of several image variants that may be available within this image set.
largesquare	Image Variant	One of several image variants that may be available within this image set.
id	UUID	A unique identifier for the image set. (This is useful mainly for debugging by Bloomreach engineers.)
localeString	null	Deprecated. Please do not use in implementations.
displayName	String	Deprecated. Please do not use in implementations.
fileName	String	Deprecated. Please do not use in implementations.

Image variant properties

Property	Type	Description
height	int	The image's rendered height in pixels
width	int	The image's rendered width in pixels
size	int	The binary data size in bytes
contentType	String	Always 'hippogallery:image'.
mimeType	String	A MIME type string detected from the image name and binary data
lastModified	int	The UNIX style timestamp integer value for the moment this image variant was last changed, due to an event such as applying a manual crop
links.site.href	URL	The URL at which the binary image data for this image variant is available
links.site.type	String	Always "resource"
name	String	Deprecated. Please do not use in implementations.
displayName	String	Deprecated. Please do not use in implementations.
filename	String	Deprecated. Please do not use in implementations.

Example: https://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?pageSize=2&page=1

{
    "offset": 0,
    "total": 20,
    "first": {
        "number": 1,
        "links": {
            "site": {
                "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=1&limit=10&pageSize=2",
                "type": "internal"
            },
            "self": {
                "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=1&limit=10&pageSize=2",
                "type": "external"
            }
        }
    },
    "previous": null,
    "current": {
        "number": 1,
        "links": {
            "site": {
                "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=1&limit=10&pageSize=2",
                "type": "internal"
            },
            "self": {
                "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=1&limit=10&pageSize=2",
                "type": "external"
            }
        }
    },
    "next": {
        "number": 2,
        "links": {
            "site": {
                "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=2&limit=10&pageSize=2",
                "type": "internal"
            },
            "self": {
                "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=2&limit=10&pageSize=2",
                "type": "external"
            }
        }
    },
    "last": {
        "number": 10,
        "links": {
            "site": {
                "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=10&limit=10&pageSize=2",
                "type": "internal"
            },
            "self": {
                "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=10&limit=10&pageSize=2",
                "type": "external"
            }
        }
    },
    "pages": [
        {
            "number": 1,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=1&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=1&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 2,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=2&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=2&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 3,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=3&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=3&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 4,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=4&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=4&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 5,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=5&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=5&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 6,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=6&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=6&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 7,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=7&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=7&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 8,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=8&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=8&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 9,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=9&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=9&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        },
        {
            "number": 10,
            "links": {
                "site": {
                    "href": "/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=10&limit=10&pageSize=2",
                    "type": "internal"
                },
                "self": {
                    "href": "http://developers.bloomreach.io/delivery/images/v1/content/gallery/channel-templates/referencespa/articles?page=10&limit=10&pageSize=2",
                    "type": "external"
                }
            }
        }
    ],
    "size": 2,
    "items": [
        {
            "name": "an-insight-into-the-function-of-stick-stud-welding.png",
            "displayName": "an-insight-into-the-function-of-stick-stud-welding.png",
            "banner": null,
            "small": null,
            "large": null,
            "smallsquare": null,
            "mediumsquare": null,
            "largesquare": null,
            "thumbnail": {
                "name": "hippogallery:thumbnail",
                "displayName": "hippogallery:thumbnail",
                "height": 39,
                "width": 60,
                "filename": "an-insight-into-the-function-of-stick-stud-welding.png",
                "mimeType": "image/png",
                "lastModified": 1602702933862,
                "contentType": "hippogallery:image",
                "size": 6078,
                "links": {
                    "site": {
                        "href": "https://developers.bloomreach.io/delivery/resources/thumbnail/content/gallery/channel-templates/referencespa/articles/an-insight-into-the-function-of-stick-stud-welding.png",
                        "type": "resource"
                    }
                }
            },
            "original": {
                "name": "hippogallery:original",
                "displayName": "hippogallery:original",
                "height": 846,
                "width": 1280,
                "filename": null,
                "mimeType": "image/png",
                "lastModified": 1602702933862,
                "contentType": "hippogallery:image",
                "size": 2055187,
                "links": {
                    "site": {
                        "href": "https://developers.bloomreach.io/delivery/resources/content/gallery/channel-templates/referencespa/articles/an-insight-into-the-function-of-stick-stud-welding.png",
                        "type": "resource"
                    }
                }
            },
            "description": null,
            "fileName": "an-insight-into-the-function-of-stick-stud-welding.png",
            "contentType": "xm:imageset",
            "localeString": null,
            "id": "56d0ae42-b204-4445-ac72-27543fff5056"
        },
        {
            "name": "boost-development.png",
            "displayName": "boost-development.png",
            "banner": null,
            "small": null,
            "large": null,
            "smallsquare": null,
            "mediumsquare": null,
            "largesquare": null,
            "thumbnail": {
                "name": "hippogallery:thumbnail",
                "displayName": "hippogallery:thumbnail",
                "height": 39,
                "width": 60,
                "filename": "boost-development.png",
                "mimeType": "image/png",
                "lastModified": 1602702933252,
                "contentType": "hippogallery:image",
                "size": 7270,
                "links": {
                    "site": {
                        "href": "https://developers.bloomreach.io/delivery/resources/thumbnail/content/gallery/channel-templates/referencespa/articles/boost-development.png",
                        "type": "resource"
                    }
                }
            },
            "original": {
                "name": "hippogallery:original",
                "displayName": "hippogallery:original",
                "height": 846,
                "width": 1280,
                "filename": null,
                "mimeType": "image/png",
                "lastModified": 1602702933252,
                "contentType": "hippogallery:image",
                "size": 2234648,
                "links": {
                    "site": {
                        "href": "https://developers.bloomreach.io/delivery/resources/content/gallery/channel-templates/referencespa/articles/boost-development.png",
                        "type": "resource"
                    }
                }
            },
            "description": null,
            "fileName": "boost-development.png",
            "contentType": "xm:imageset",
            "localeString": null,
            "id": "5cf172d3-b7db-46fb-a4a8-ce35b015a8e4"
        }
    ]
}