Product images

Reads, uploads and deletes images for a catalog product. All routes require an API key with the catalog scope; uploads and deletes require a write-enabled key.

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.

These routes use the shared product ID space for simple products, SKUs, variations and services.

Bitrix24 API: catalog.productImage.list, catalog.productImage.get, catalog.productImage.add, catalog.productImage.delete Scope: catalog

Safe handling of the image address

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 a server-side request forgery (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.

The downloadUrl download link is not included in the response because it may contain a webhook path and secret. The API neither proxies nor downloads the file. A detailUrl containing a webhook path is also rejected.

Upload product image

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

Uploads a catalog product image from base64 content: a detail picture, a preview picture or a gallery image. The request body is flat JSON.

Parameters

Request fields (body)

The body accepts no other fields: an extra field such as description returns 400 INVALID_PARAMS. The request body limit is 40 MiB.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/catalog-products/7257/images" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MORE_PHOTO",
    "fileName": "photo.png",
    "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg=="
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/catalog-products/7257/images" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MORE_PHOTO",
    "fileName": "photo.png",
    "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg=="
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/7257/images', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'MORE_PHOTO',
    fileName: 'photo.png',
    fileContent: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==',
  }),
})

const { success, data } = await res.json()
console.log('Image ID:', data.id)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-products/7257/images', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'MORE_PHOTO',
    fileName: 'photo.png',
    fileContent: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==',
  }),
})

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

Response fields

A successful upload responds with HTTP status 201 Created.

Response example

{
  "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"
  }
}

Error response example

400 — an unknown type, an empty file name, content that is not base64, or an extra body field:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "type, fileName and base64 fileContent are required"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• Replacing the detail and preview pictures. A product has one detail picture and one preview picture. Uploading DETAIL_PICTURE or PREVIEW_PICTURE again replaces the previous one: the response carries a new id, and the previous id can no longer be read. MORE_PHOTO adds a picture to the gallery.
• File content is not checked. Text uploaded as photo.png is saved as a picture. Make sure fileContent is an image before uploading.
• Identical content shares one file. Uploading the same content again creates an image with a new id, but its name and detailUrl come from the earlier file, even if fileName carries a different name.

See also

• Product images
• List product images
• Get product image
• Delete product image
• Catalog products