API reference image converter - WEBSALE Dokumentation

The interface under /images/ provides comprehensive functions for managing images of various formats in our shop system. Through various endpoints, you can upload, convert, and delete images as well as retrieve the corresponding URLs.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	PUT	POST	DELETE
Image upload	images/

Supported image formats

Bitmap
FITS
GIF
Graphics Kernel System
JPEG
NIFF
PM
PNG
XFIG
XPM
TIFF
GIMP XCF
webp
AVIF

Data fields of a directory

Name	Type	Usage
name	String	The name of the directory
path	String	The path to the directory
subDirectories	Array	An array of subdirectories

Example

{
    "name": "products",
    "path": "products",
    "subDirectories": [
        {
            "name": "thumbnail",
            "path": "products/thumbnail",
            "subDirectories": []
        },
        {
            "name": "normal",
            "path": "products/normal",
            "subDirectories": []
        },
        {
            "name": "large",
            "path": "products/large",
            "subDirectories": []
        }
    ]
}

Methods for managing images

GET images/url/{typeId}

This endpoint returns the URL of an image based on the specified type (typeId) and, optionally, the desired format. It is used to determine the storage location of an image in the system — particularly when the path is not known after upload.
Valid values for typeId are:

categories for category images,
products for product images,
appImages for images within the app interface.

The returned URL points to the target directory for the respective image type, so that image data can subsequently be correctly stored or referenced. Read permissions are required.

Example

https://www.<your-shop>.de/admin/api/v1/images/url/products?formatNodeId=content.imageFormat.normal

Response

{
    "success": true,
    "url": "//content.<your-shop>.de"
}

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read category, product, or app data.
400 Bad Request	”invalidValue”
400 Bad Request	”missing”	`subshopId` or `formatNodeId` was not provided.

GET images/directories/{typeId}

This endpoint returns the structure of the available image directories as a tree structure. Depending on the value of the typeId parameter, either source directories (source) or target directories (target) are returned. The response contains a hierarchical representation of the existing folders and subfolders.

Example

https://www.<your-shop>.de/admin/api/v1/images/directories/source

Response

{
    "items": [
        {
            "name": "myDir1",
            "path": "myDir1",
            "subDirectories": [
                {
                    "name": "myDir2",
                    "path": "myDir1/myDir2",
                    "subDirectories": []
                },
                {
                    "name": "myDir3",
                    "path": "myDir1/myDir3",
                    "subDirectories": [
                        {
                            "name": "myDir4",
                            "path": "myDir1/myDir3/myDir4",
                            "subDirectories": []
                        }
                    ]
                }
            ]
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read converted images.
400 Bad Request	”invalidValue”

GET images/convert/results

This endpoint returns a paginated list of the results of completed image conversions. For each converted image, information such as source file, target file, target format, file size, conversion duration, and processing status is returned. This makes it possible to track whether and how an image has been successfully converted to various formats.

Query parameters

Name	Type	Usage
size	Number (optional)	Number of results per page. Default value is used if not specified.
pageToken	String (optional)	Token for the next page. Returned in the response as `nextPageToken`.

Example

https://www.<your-shop>.de/admin/api/v1/images/convert/results?size=200

Response

{
    "items": [
        {
            "duration": 0,
            "fileSize": "55 KB",
            "format": "app",
            "formatId": "content.imageFormat.app",
            "message": "success",
            "output": "app/Screenshot 2025-03-24 222742.png",
            "outputFilename": "Screenshot 2025-03-24 222742.png",
            "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png",
            "sourceFilename": "Screenshot 2025-03-24 222742.png",
            "status": "success"
        },
        {
            "duration": 1,
            "fileSize": "55 KB",
            "format": "normal category",
            "formatId": "content.imageFormat.normalCategory",
            "message": "success",
            "output": "categories/normal/Screenshot 2025-03-24 222742.png",
            "outputFilename": "Screenshot 2025-03-24 222742.png",
            "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png",
            "sourceFilename": "Screenshot 2025-03-24 222742.png",
            "status": "success"
        },
        {
            "duration": 1,
            "fileSize": "55 KB",
            "format": "normal product",
            "formatId": "content.imageFormat.normalProduct",
            "message": "success",
            "output": "products/normal/Screenshot 2025-03-24 222742.png",
            "outputFilename": "Screenshot 2025-03-24 222742.png",
            "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png",
            "sourceFilename": "Screenshot 2025-03-24 222742.png",
            "status": "success"
        },
        {
            "duration": 1,
            "fileSize": "10 KB",
            "format": "thumbnail product",
            "formatId": "content.imageFormat.thumbnailProduct",
            "message": "success",
            "output": "products/thumbnail/Screenshot 2025-03-24 222742.png",
            "outputFilename": "Screenshot 2025-03-24 222742.png",
            "source": "upload/9fcd26d4c240/Screenshot 2025-03-24 222742.png",
            "sourceFilename": "Screenshot 2025-03-24 222742.png",
            "status": "success"
        }
    ],
    "totalCount": 4,
    "endReached": true,
    "nextPageToken": "MjAw"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read converted images.

GET images/convert/status

This endpoint returns the current status of a running image conversion process, or the last known status of a completed one. It returns information such as progress, the number of successful or failed conversions, and timer data (start time, end time, duration). The endpoint allows monitoring and evaluation of image conversion processes in the system.

Example

https://www.<your-shop>.de/admin/api/v1/images/convert/status

Response

{
    "canceled": true,
    "counter": {
        "error": 0,
        "skipped": 0,
        "success": 0,
        "warning": 0
    },
    "formatCounter": {
        "error": 0,
        "skipped": 0,
        "success": 0,
        "warning": 0
    },
    "progress": {
        "finished": 0,
        "percentage": 0,
        "total": 0
    },
    "progressFormat": {
        "finished": 0,
        "percentage": 0,
        "total": 0
    },
    "running": false,
    "status": "ready",
    "timer": {
        "duration": 0,
        "end": 0,
        "start": 0
    },
    "usedFormats": []
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read converted images.
503 Service Unavailable	”internalError”	The conversion process cannot be checked.

GET images/report/products

This endpoint returns a report on the use of product images in the shop system. It lists both missing images (missingImages) and unused images (unusedImages). The report helps identify image files that are no longer assigned to an active product or that are missing in the system, and thus supports the optimization of image data management.

Example

https://www.<your-shop>.de/admin/api/v1/images/report/products

Response

{
    "createdAt": "2025-04-25T15:55:39.000Z",
    "id": 1,
    "missingImages": [],
    "unusedImages": [
        {
            "filename": "th.jpg",
            "format": ""
        },
        {
            "filename": "Screenshot 2025-03-24 222742.png",
            "format": ""
        },
        {
            "filename": "th.jpg",
            "format": ""
        },
        {
            "filename": "Screenshot 2025-03-24 222742.png",
            "format": ""
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read product data.

POST images/upload

This endpoint enables uploading an image to the shop system. The image is transmitted as a Base64-encoded string in the request body. Additionally, it can be specified which formats the image should be converted to. After a successful upload, the path to the stored image file is returned.

Example

https://www.<your-shop>.de/admin/api/v1/images/upload

Request body

{
    "fileName": [
        "Screenshot 2025-03-24 222742.png"
    ],
    "formats": [
        "content.imageFormat.normalProduct",
        "content.imageFormat.thumbnailProduct"
    ],
    "imageData": [
        "iVBORw0KGgoAAAANSUhEUgAAAU8AAAJcCAYAAAB5ZyZaAAAAAXNSR0IArs4c6QAAAA..."
    ]
}

Response

{
    "path": "upload/c14cb01ea580",
    "size": 1,
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to publish converted images.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`formats` was not provided.
400 Bad Request	”invalidValue”	An image format is invalid. `imageData` is invalid.
400 Bad Request	”invalidFormat”	The `formats` field is not an array of strings. The `fileName` field is neither a string nor an array of strings. The `imageData` field is neither a string nor an array of strings.
400 Bad Request	”invalidFileFormat”	The image has an invalid format.
400 Bad Request	”unknownDataField”	The request body contains something other than `fileName`, `imageData`, and `formats`.
503 Service Unavailable	”internalError”	The image upload failed.

POST images/upload/convert

This endpoint enables uploading an image with immediate subsequent conversion to one or more defined target formats. The image is transmitted as a Base64-encoded string in the request body. In contrast to the regular upload, the conversion is automatically triggered here, so that optimized or format-adapted variants can be created directly. After completion, an overview of the generated image files is returned.

Example

https://www.<your-shop>.de/admin/api/v1/images/upload/convert

Request body

{
    "fileName": "myPicture.png",
    "formats": [
        "content.imageFormat.normalCategory",
        "content.imageFormat.normalProduct"
    ],
    "imageData": "iVBORw0KGgoAAAANSUhEUgAAAU8AAAJcCAYAAAB5ZyZaAAAAAXNS..."
}

Response

{
    "items": [
        {
            "duration": 0,
            "fileSize": "55 KB",
            "format": "normal category",
            "formatId": "content.imageFormat.normalCategory",
            "message": "success",
            "output": "categories/normal/myPicture.png",
            "outputFilename": "myPicture.png",
            "source": "upload/169357275289/myPicture.png",
            "sourceFilename": "myPicture.png",
            "status": "success"
        },
        {
            "duration": 0,
            "fileSize": "55 KB",
            "format": "normal product",
            "formatId": "content.imageFormat.normalProduct",
            "message": "success",
            "output": "products/normal/myPicture.png",
            "outputFilename": "myPicture.png",
            "source": "upload/169357275289/myPicture.png",
            "sourceFilename": "myPicture.png",
            "status": "success"
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to publish converted images. The image type is considered in the permissions.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`formats` was not provided.
400 Bad Request	”invalidValue”	An image format is invalid. `imageData` is invalid. Multiple images were provided.
400 Bad Request	”invalidFormat”	The `formats` field is not an array of strings. The `fileName` field is neither a string nor an array of strings. The `imageData` field is neither a string nor an array of strings.
400 Bad Request	”invalidFileFormat”	The image has an invalid format.
400 Bad Request	”unknownDataField”	The request body contains something other than `fileName`, `imageData`, and `formats`.
503 Service Unavailable	”internalError”	Converting the image failed.
503 Service Unavailable	”serviceUnavailable”	The conversion process could not be started.

POST images/report

This endpoint starts the check for missing or unused image files in the system. Execution is asynchronous: no direct result is returned after a successful start of the check. The complete report can then be retrieved via GET /images/report/. The endpoint ensures that image data can be regularly checked for consistency.

Example

https://www.<your-shop>.de/admin/api/v1/images/report

Request body

{}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create products.
503 Service Unavailable	”serviceUnavailable”	The check could not be started.

POST images/convert/start

This endpoint starts the conversion process for images stored in the system. The images are converted into the respectively defined target formats (e.g. different sizes or file formats). Execution is asynchronous, but a direct response about the converted images is provided after the process is started. The progress and status of the conversion can be queried later via the endpoint GET /images/convert/status.

Example

https://www.<your-shop>.de/admin/api/v1/images/convert/start

Request body

{
    "action": "manual",
    "source": "directory",
    "formatList": [
        "content.imageFormat.app",
        "content.imageFormat.normalCategory",
        "content.imageFormat.normalProduct",
        "content.imageFormat.thumbnailProduct"
    ],
    "directory": "upload/e6122e69f1d0"
}

Response

{
    "canceled": true,
    "counter": {
        "error": 0,
        "skipped": 0,
        "success": 0,
        "warning": 0
    },
    "formatCounter": {
        "error": 0,
        "skipped": 0,
        "success": 4,
        "warning": 0
    },
    "progress": {
        "finished": 1,
        "percentage": 100,
        "total": 1
    },
    "progressFormat": {
        "finished": 4,
        "percentage": 100,
        "total": 4
    },
    "running": false,
    "status": "finished",
    "timer": {
        "duration": 1745857938,
        "end": 1745857938,
        "start": 0
    },
    "usedFormats": [
        "content.imageFormat.app",
        "content.imageFormat.normalCategory",
        "content.imageFormat.normalProduct",
        "content.imageFormat.thumbnailProduct"
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to publish converted images.
400 Bad Request		Request body could not be loaded. The format was not found. The format has an invalid source directory, or an invalid source directory was specified. No formats exist. The `source` field contains something other than `format` or `directory`.
503 Service Unavailable	”serviceUnavailable”	The conversion process could not be started.
503 Service Unavailable	”internalError”	The conversion status cannot be retrieved.

POST images/convert/cancel

This endpoint cancels a currently running image conversion process. Cancellation is not asynchronous; a direct response on the converted images is provided immediately. After execution, the status of the conversion process can be queried again via the endpoint GET /images/convert/status. The cancellation operation requires appropriate permissions.

Example

https://www.<your-shop>.de/admin/api/v1/images/convert/cancel

Request body

{}

Response

{
    "cancelStatus": "triggered",
    "canceled": true,
    "counter": {
        "error": 0,
        "skipped": 0,
        "success": 0,
        "warning": 0
    },
    "formatCounter": {
        "error": 0,
        "skipped": 0,
        "success": 2,
        "warning": 0
    },
    "progress": {
        "finished": 1,
        "percentage": 100,
        "total": 1
    },
    "progressFormat": {
        "finished": 2,
        "percentage": 100,
        "total": 2
    },
    "running": false,
    "status": "finished",
    "timer": {
        "duration": 1745858133,
        "end": 1745858133,
        "start": 0
    },
    "usedFormats": [
        "content.imageFormat.normalProduct",
        "content.imageFormat.thumbnailProduct"
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to publish converted images.
503 Service Unavailable	”internalError”	The conversion process cannot be checked.

POST images/directories/{typeId}

Creates a directory. For typeId = source, these are source directories; for typeId = target, these are target directories.

Example

https://www.<your-shop>.de/admin/api/v1/images/directories/target

Request body

{
    "path": "myDir",
    "name": "test"
}

Response

{
    "items": [
        {
            "name": "myDir",
            "path": "myDir",
            "subDirectories": [
                {
                    "name": "test",
                    "path": "myDir/test",
                    "subDirectories": []
                }
            ]
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create converted images.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue”	`name` or `path` is invalid.
400 Bad Request	”missing”	`name` was not provided.
503 Service Unavailable	”internalError”	Creating the directory failed.

DELETE images/directories/{typeId}

This endpoint deletes a directory within the specified area (source or target) for image files. The path to the parent directory and the name of the folder to be deleted can be defined via the request body. After successful deletion, the updated directory structure without the deleted directory is returned as a tree structure.

Example

https://www.<your-shop>.de/admin/api/v1/images/directories/target

Request body

{
    "path": "myDir/test"
}

Response

{
    "items": [
        {
            "name": "myDir",
            "path": "myDir",
            "subDirectories": []
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete converted images.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue”	path is missing or empty.
404 Not Found		The directory was not found.
503 Service Unavailable	”internalError”	Deleting the directory failed.

DELETE images/upload/{typeId}

This endpoint deletes one or more images within a specified area (categories, products, or appImages). The name of the file(s) to be deleted is provided via the fileName field in the request body, either as a string or as an array of strings. Optionally, the formats field can be used to specify which image formats should be considered; otherwise all formats are deleted. The endpoint carefully checks the validity of the provided parameters and handles both single and multiple deletions.

Example

https://www.<your-shop>.de/admin/api/v1/images/upload/appImages

Request body

{
    "formats": [
        "content.imageFormat.app"
    ],
    "fileName": "th_1740130633.jpg"
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write category, product, or app data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`subshopId` or `fileName` was not provided.
400 Bad Request	”invalidValue”	`subshopId` is invalid. An image format is invalid.
400 Bad Request	”invalidFormat”	The `formats` field is not an array of strings. The `fileName` field is neither a string nor an array of strings.
400 Bad Request	”unknownDataField”	The request body contains something other than `fileName` and `formats`.
503 Service Unavailable	”internalError”	Deleting images failed.

DELETE images/upload/{typeId}/{filename}

This endpoint deletes a specific image within a specified area (categories, products, or appImages). The file name to be deleted is passed directly as a path parameter (filename). Additionally, further file names (fileName) can be specified in the request body, either as a single string or as an array of strings. The optional formats field can be used to specify which image formats should be deleted; otherwise all formats are considered. The endpoint supports both single image deletion and combined deletion of multiple images.

Example

https://www.<your-shop>.de/admin/api/v1/images/upload/appImages/th_1740129668.jpg

Request body

{
    "formats": [
        "content.imageFormat.app"
    ]
}

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write category, product, or app data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`subshopId` or `fileName` was not provided.
400 Bad Request	”invalidValue”	`subshopId` is invalid. An image format is invalid.
400 Bad Request	”invalidFormat”	The `formats` field is not an array of strings. The `fileName` field is neither a string nor an array of strings.
400 Bad Request	”unknownDataField”	The request body contains something other than `fileName` and `formats`.
503 Service Unavailable	”internalError”	Deleting images failed.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Supported image formats

​Data fields of a directory

​Example

​Methods for managing images

​GET images/url/{typeId}

​GET images/url/{typeId}

​Example

​Response

​GET images/directories/{typeId}

​GET images/directories/{typeId}

​Example

​Response

​Error codes

​GET images/convert/results

​Query parameters

​Example

​Response

​Error codes

​GET images/convert/status

​Example

​Response

​Error codes

​GET images/report/products

​Example

​Response

​Error codes

​POST images/upload

​Example

​Request body

​Response

​Error codes

​POST images/upload/convert

​Example

​Request body

​Response

​Error codes

​POST images/report

​Example

​Request body

​Response

​Error codes

​POST images/convert/start

​Example

​Request body

​Response

​Error codes

​POST images/convert/cancel

​Example

​Request body

​Response

​Error codes

​POST images/directories/{typeId}

​POST images/directories/{typeId}

​Example

​Request body

​Response

​Error codes

​DELETE images/directories/{typeId}

​DELETE images/directories/{typeId}

​Example

​Request body

​Response

​Error codes

​DELETE images/upload/{typeId}

​DELETE images/upload/{typeId}

​Example

​Request body

​Response

​Error codes

​DELETE images/upload/{typeId}/{filename}

​DELETE images/upload/{typeId}/{filename}

​Example

​Request body

​Response

​Error codes

​Support

Supported methods

Supported image formats

Data fields of a directory

Example

Methods for managing images

GET images/url/{typeId}

GET images/url/{typeId}

Example

Response

GET images/directories/{typeId}

GET images/directories/{typeId}

Example

Response

Error codes

GET images/convert/results

Query parameters

Example

Response

Error codes

GET images/convert/status

Example

Response

Error codes

GET images/report/products

Example

Response

Error codes

POST images/upload

Example

Request body

Response

Error codes

POST images/upload/convert

Example

Request body

Response

Error codes

POST images/report

Example

Request body

Response

Error codes

POST images/convert/start

Example

Request body

Response

Error codes

POST images/convert/cancel

Example

Request body

Response

Error codes

POST images/directories/{typeId}

POST images/directories/{typeId}

Example

Request body

Response

Error codes

DELETE images/directories/{typeId}

DELETE images/directories/{typeId}

Example

Request body

Response

Error codes

DELETE images/upload/{typeId}

DELETE images/upload/{typeId}

Example

Request body

Response

Error codes

DELETE images/upload/{typeId}/{filename}

DELETE images/upload/{typeId}/{filename}

Example

Request body

Response

Error codes

Support