For AI agents: markdown of this page — /docs-content-en/entities/catalog-products/images-list.md documentation index — /llms.txt

List product images

GET /v1/catalog-products/:productId/images

Returns all native images of a catalog product in one list: the detail picture, the preview picture and gallery images.

Files stored in other custom File properties of the product (propertyNNN) are not included in the list.

Parameters

Parameter Type Required Description
ParameterproductId (path) Typenumber Requiredyes DescriptionProduct ID. List: GET /v1/catalog-products. The ID of an SKU from GET /v1/catalog-skus, an offer from GET /v1/catalog-offers or a service from GET /v1/catalog-services also works

Pagination. The method has no start, limit or offset parameters. Vibecode walks through the Bitrix24 result pages internally and returns all product images in one call.

The generic filter parameter is not applied by this endpoint. By default, the API preserves the previous HTTP 200 response and data, adds Warning: 299 - "filter is not supported on this endpoint and was ignored", and records unsupported-filter use in the server log.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-products/7257/images" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-products/7257/images" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/7257/images', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log('Images:', meta.total)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/7257/images', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionProduct images
Fielddata[].id Typenumber DescriptionImage ID
Fielddata[].productId Typenumber DescriptionID of the product that owns the image
Fielddata[].type Typestring DescriptionImage type: DETAIL_PICTURE — detail picture, PREVIEW_PICTURE — preview picture, MORE_PHOTO — gallery image
Fielddata[].name Typestring DescriptionFile name
Fielddata[].createTime Typestring | null DescriptionCreation time in ISO 8601 format with a UTC offset, or null
Fielddata[].detailUrl Typestring DescriptionImage address — a path starting with / relative to the Bitrix24 account origin, or an absolute http/https URL. Access without a Bitrix24 account session is not guaranteed. Treat it as untrusted input — see Product images
Fieldmeta.total Typenumber DescriptionNumber of images in data

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 38993,
      "productId": 7257,
      "type": "MORE_PHOTO",
      "name": "photo.png",
      "createTime": "2026-10-08T20:59:02+00:00",
      "detailUrl": "https://cdn.bitrix24.com/b00000000/iblock/2ba/2bae996b883855a3997fde84f01c7aee/photo.png"
    },
    {
      "id": 38995,
      "productId": 7257,
      "type": "DETAIL_PICTURE",
      "name": "detail.png",
      "createTime": "2026-10-08T20:59:02+00:00",
      "detailUrl": "https://cdn.bitrix24.com/b00000000/iblock/b0f/b0fde5347f43d18bbd880e0859133c7c/detail.png"
    },
    {
      "id": 38997,
      "productId": 7257,
      "type": "PREVIEW_PICTURE",
      "name": "preview.png",
      "createTime": "2026-10-08T20:59:03+00:00",
      "detailUrl": "https://cdn.bitrix24.com/b00000000/iblock/1be/1be722feedfeb7ecf7a336500ed91684/preview.png"
    }
  ],
  "meta": {
    "total": 3
  }
}

Error response example

404 — no product with this productId exists:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Catalog product image or product not found"
  }
}

Errors

HTTP Code Description
HTTP200 CodeWarning: 299 DescriptionThe filter is ignored by default; previous data is preserved and the warning is sent in the Warning header.
HTTP400 (strict mode only) CodeUNSUPPORTED_FILTER DescriptionThe server mode is disabled by default; until it is enabled, the endpoint preserves HTTP 200 and the previous data.
HTTP400 CodeINVALID_PARAMS DescriptionproductId is not a canonical positive integer — for example, abc, 0 or a value outside the JavaScript safe integer range
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo product with this productId exists
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 returned an incomplete or inconsistent list, or a response that failed the shape and safety checks. A partial list is never returned
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is invalid
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the catalog scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the catalog
HTTP429 CodeRATE_LIMITED DescriptionThe request limit was reached. Retry after the time in the Retry-After header
HTTP429 CodeOPERATION_TIME_LIMIT DescriptionThe Bitrix24 operation-time limit was reached. Retry after the time in the Retry-After header
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time. Retry after the time in the Retry-After header

Full list of common API errors — Errors.

See also