Skip to main content
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/infoEndpointsGETPUTPOSTDELETE
Image uploadimages/

​
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

NameTypeUsage
nameStringThe name of the directory
pathStringThe path to the directory
subDirectoriesArrayAn 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}

​
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"
}
ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or 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}

​
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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or 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

NameTypeUsage
sizeNumber (optional)Number of results per page. Default value is used if not specified.
pageTokenString (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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to publish converted images.
400 Bad RequestRequest 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to publish converted images. The image type is considered in the permissions.
400 Bad RequestRequest 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to publish converted images.
400 Bad RequestRequest 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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to publish converted images.
503 Service Unavailable”internalError”The conversion process cannot be checked.

​
POST images/directories/{typeId}

​
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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to create converted images.
400 Bad RequestRequest 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}

​
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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to delete converted images.
400 Bad RequestRequest body could not be loaded.
400 Bad Request”invalidValue”path is missing or empty.
404 Not FoundThe directory was not found.
503 Service Unavailable”internalError”Deleting the directory failed.

​
DELETE images/upload/{typeId}

​
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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to write category, product, or app data.
400 Bad RequestRequest 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}

​
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

ErrorTypeReason
401 UnauthorizedNot authorized: you are not logged in or do not have the required permissions to write category, product, or app data.
400 Bad RequestRequest 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.