Attachments API
Inventory attachment API for uploading, downloading, tagging, previewing, and deleting item files and product images.
Generated from the Celerp 2.5.0 OpenAPI schema, 21 September 2026.
POST /items/attachments/bulk
Bulk Attach Item Files (Legacy)
Deprecated: redirects to /items/files/bulk.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
override_hero | query | -- | boolean | Whether a newly imported image may replace the item's existing featured image. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the result of the bulk attach item files (legacy) operation. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/items/attachments/bulk \
-H "Authorization: Bearer $TOKEN"POST /items/files/bulk
Bulk Attach Inventory Files
Attach many files to items at once from a ZIP archive. Files are matched to items by SKU in the file name; `SKU.jpg` becomes the main image and `SKU-img-2.jpg` an extra image.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
override_hero | query | -- | boolean | Whether a newly imported image may replace the item's existing featured image. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the files matched to items, the files that matched no SKU, any errors, and a summary report. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/items/files/bulk \
-H "Authorization: Bearer $TOKEN"POST /items/{entity_id}/attachments
Upload Inventory Attachment
Upload a file and attach it to an item. Pass `attachment_type=view_360` for a 360 image or video.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
attachment_type | query | -- | string, optional | Attachment category to assign to the uploaded item file. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the new attachment record. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/items/:entity_id/attachments \
-H "Authorization: Bearer $TOKEN"DELETE /items/{entity_id}/attachments/{att_id}
Delete Inventory Attachment
Remove one attachment from an item.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
att_id | path | yes | string | Identifier of the attachment. |
Responses
| Status | Description | Body |
|---|---|---|
204 | Success. No response body is returned. | -- |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X DELETE http://localhost:8000/items/:entity_id/attachments/:att_id \
-H "Authorization: Bearer $TOKEN"PUT /items/{entity_id}/attachments/{att_id}/preview
Set Inventory Preview Image
Set which image attachment is shown as the item's preview.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
att_id | path | yes | string | Identifier of the attachment. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the updated inventory preview image or update result. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X PUT http://localhost:8000/items/:entity_id/attachments/:att_id/preview \
-H "Authorization: Bearer $TOKEN"POST /items/{entity_id}/files
Upload Inventory Item File
Upload a file and attach it to an item. An image becomes the main image when the item has none yet, or when `as_hero` is set.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
document_tag | query | -- | string, optional | Document tag used to classify the uploaded file. |
as_hero | query | -- | boolean | Whether an uploaded image becomes the item's main image, replacing the current one. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the stored file's details and whether it is now the item's main image. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/items/:entity_id/files \
-H "Authorization: Bearer $TOKEN"GET /items/{entity_id}/files/{file_id}
Download Inventory Item File
Download a file attached to an item.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
file_id | path | yes | string | Identifier of the uploaded or stored file. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the generated file or download response. | -- |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X GET http://localhost:8000/items/:entity_id/files/:file_id \
-H "Authorization: Bearer $TOKEN"DELETE /items/{entity_id}/files/{file_id}
Delete Inventory Item File
Delete a file attached to an item.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
file_id | path | yes | string | Identifier of the uploaded or stored file. |
Responses
| Status | Description | Body |
|---|---|---|
204 | Success. No response body is returned. | -- |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X DELETE http://localhost:8000/items/:entity_id/files/:file_id \
-H "Authorization: Bearer $TOKEN"PATCH /items/{entity_id}/files/{file_id}/description
Update Inventory File Description
Update inventory file description with the supplied fields.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
file_id | path | yes | string | Identifier of the uploaded or stored file. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the updated inventory file description or update result. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X PATCH http://localhost:8000/items/:entity_id/files/:file_id/description \
-H "Authorization: Bearer $TOKEN"POST /items/{entity_id}/files/{file_id}/hero
Set Featured Inventory Image
Mark a file as the hero (featured) image. Must be an image MIME type.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
file_id | path | yes | string | Identifier of the uploaded or stored file. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the updated featured inventory image or update result. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/items/:entity_id/files/:file_id/hero \
-H "Authorization: Bearer $TOKEN"POST /items/{entity_id}/files/{file_id}/tag
Tag Inventory Item File
Set the tag on a file attached to an item.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
file_id | path | yes | string | Identifier of the uploaded or stored file. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the updated item record. | object |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X POST http://localhost:8000/items/:entity_id/files/:file_id/tag \
-H "Authorization: Bearer $TOKEN"GET /items/{entity_id}/files/{file_id}/thumbnail
Get Item File Thumbnail
Get the small JPEG preview of an item image, as shown in the item list. A preview is made on first view for images uploaded before previews existed.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
entity_id | path | yes | string | Identifier of the requested Celerp record. |
file_id | path | yes | string | Identifier of the uploaded or stored file. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Returns the JPEG preview. | -- |
422 | The request failed validation. The response lists each invalid field and why. | HTTPValidationError |
Example
curl -X GET http://localhost:8000/items/:entity_id/files/:file_id/thumbnail \
-H "Authorization: Bearer $TOKEN"