# Product images

Returns metadata for a catalog product's images. Both methods are read-only, require an API key with the `catalog` scope, and do not return file bytes.

The methods return only the product's native images: its detail picture, preview picture, and `MORE_PHOTO` gallery items. Files stored in other custom File properties (`propertyNNN`) are not included.

Bitrix24 API: `catalog.productImage.list`, `catalog.productImage.get`
Scope: `catalog`

## Operations

| Method | Path | What it returns |
|-------|------|----------------|
| GET | `/v1/catalog-products/:productId/images` | A snapshot of the product's image metadata as one list |
| GET | `/v1/catalog-products/:productId/images/:imageId` | One image that belongs to the specified product |

`productId` and `imageId` are positive integers. A non-canonical value or one outside JavaScript's safe integer range returns `400 INVALID_PARAMS`.

## Authorization

A personal key is passed in `X-Api-Key`. An application key also requires a user session in `Authorization: Bearer ...`. A read-only key works when it has the `catalog` scope.

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

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

## Image fields

Every object contains exactly six fields:

| Field | Type | Description |
|------|-----|----------|
| `id` | number | Image ID |
| `productId` | number | Owning product ID |
| `type` | string | `DETAIL_PICTURE`, `PREVIEW_PICTURE`, or `MORE_PHOTO` |
| `name` | string | File name |
| `createTime` | string \| null | Creation time in the format returned by Bitrix24, or `null` |
| `detailUrl` | string | Image address: a root-relative path or an absolute `http`/`https` URL; access without a Bitrix24 account session is not guaranteed |

The native `downloadUrl` field is not published because it may contain a signed URL. The API neither proxies nor downloads the file.

## Responses

The method returns a single snapshot of the product's images and accepts no pagination parameters. Vibecode collects Bitrix24's internal pages itself. `meta.total` must equal the number of items in `data`; if the page walk is interrupted, an internal limit is reached, or Bitrix24 returns an inconsistent envelope, Vibecode responds with `502` instead of publishing partial data. Clients do not need to send `start`, `limit`, or `offset`: those parameters are not part of this route contract.

```json
{
  "success": true,
  "data": [
    {
      "id": 93,
      "productId": 541,
      "type": "DETAIL_PICTURE",
      "name": "product.jpg",
      "createTime": null,
      "detailUrl": "/upload/catalog/product.jpg"
    }
  ],
  "meta": {
    "total": 1
  }
}
```

A single image arrives as the same object in `data`, without `meta`.

## Safe handling of `detailUrl`

Treat `detailUrl` as untrusted input. The API validates only the URL shape and returns it without normalization. Do not make a server-side HTTP request to this address: doing so creates an SSRF risk. A path beginning with `/` is relative to the Bitrix24 account origin. For a user interface, pass the address to a safe client-side component instead of downloading it through your backend.

## Errors

| HTTP | Code | When it is returned |
|------|-----|----------------------|
| 400 | `INVALID_PARAMS` | `productId` or `imageId` is not a canonical positive integer |
| 401 | `MISSING_API_KEY` / `INVALID_API_KEY` / `TOKEN_MISSING` | The API key is missing or invalid, or it has no Bitrix24 tokens |
| 403 | `SCOPE_DENIED` / `BITRIX_ACCESS_DENIED` | The `catalog` scope is missing or Bitrix24 denied access |
| 404 | `ENTITY_NOT_FOUND` | The product or image was not found |
| 429 | `RATE_LIMITED` / `OPERATION_TIME_LIMIT` | A request or operation-time limit was reached |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned an unsafe or malformed response |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time; honor `Retry-After` |

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

## See also

- [Catalog products](/docs/entities/catalog-products)
- [Get catalog product](/docs/entities/catalog-products/get)
- [Catalog prices](/docs/entities/catalog-prices)