## 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 |
|-----------|------|:--------:|-------------|
| `productId` (path) | number | yes | Product ID. List: [`GET /v1/catalog-products`](/docs/entities/catalog-products/list). The ID of an SKU from [`GET /v1/catalog-skus`](/docs/entities/catalog-skus/list), an offer from [`GET /v1/catalog-offers`](/docs/entities/catalog-offers/list) or a service from [`GET /v1/catalog-services`](/docs/entities/catalog-services/list) 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.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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 |
|-------|------|-------------|
| `success` | boolean | Always `true` on success |
| `data` | array | Product images |
| `data[].id` | number | Image ID |
| `data[].productId` | number | ID of the product that owns the image |
| `data[].type` | string | Image type: `DETAIL_PICTURE` — detail picture, `PREVIEW_PICTURE` — preview picture, `MORE_PHOTO` — gallery image |
| `data[].name` | string | File name |
| `data[].createTime` | string \| null | Creation time in ISO 8601 format with a UTC offset, or `null` |
| `data[].detailUrl` | string | Image 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](/docs/entities/catalog-products/images) |
| `meta.total` | number | Number 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 |
|------|------|-------------|
| 400 | `INVALID_PARAMS` | `productId` is not a canonical positive integer — for example, `abc`, `0` or a value outside the JavaScript safe integer range |
| 404 | `ENTITY_NOT_FOUND` | No product with this `productId` exists |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned an incomplete or inconsistent list, or a response that failed the shape and safety checks. A partial list is never returned |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is invalid |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |
| 403 | `SCOPE_DENIED` | The key does not have the `catalog` scope |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the catalog |
| 429 | `RATE_LIMITED` | The request limit was reached. Retry after the time in the `Retry-After` header |
| 429 | `OPERATION_TIME_LIMIT` | The Bitrix24 operation-time limit was reached. Retry after the time in the `Retry-After` header |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time. Retry after the time in the `Retry-After` header |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Product images](/docs/entities/catalog-products/images)
- [Upload product image](/docs/entities/catalog-products/images-create)
- [Get product image](/docs/entities/catalog-products/images-get)
- [Delete product image](/docs/entities/catalog-products/images-delete)
- [Catalog products](/docs/entities/catalog-products)