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

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

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

Request fields (body)

Field Type Required Description
Fieldtype Typestring Requiredyes DescriptionImage type: DETAIL_PICTURE — detail picture, PREVIEW_PICTURE — preview picture, MORE_PHOTO — gallery image. Any other value is rejected before calling Bitrix24
FieldfileName Typestring Requiredyes DescriptionFile name with an extension, for example photo.png. An empty name is rejected
FieldfileContent Typestring Requiredyes DescriptionFile content in base64

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

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUploaded image
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

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

Error response example

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

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe body failed validation: an unknown type, an empty or missing fileName, fileContent that is not base64, or another field in the body
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
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe request body exceeds 40 MiB
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 did not accept the file, for example a name with a non-image extension such as note.txt
HTTP422 CodeBITRIX_ERROR DescriptionThe new image was not saved: replacing DETAIL_PICTURE or PREVIEW_PICTURE left the previous picture in place. The message is Product image was not saved
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response that failed the shape and safety checks
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 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. Uploads and deletes require a write-enabled key
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, so the write outcome is unknown. Check the product image list before retrying

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