Part images

Images are identified by an image_id. These IDs must be unique within a catalog.

In Partium, images are used for two tasks. Images can be used as reference images to enhance the Partium image search and can be displayed in the UI to describe part types. Each image belongs to exactly one part type but part types can contain multiple images.

Reference images are used by the Partium system to identify part types. Multiple images can be added to a part type to enhance the image search.

See What kind of part pictures can be used as reference images

Display images are displayed with the corresponding part in the user interface. Multiple images can be added to a part type.

The purpose of an image is defined by the info field in the image description. The info field contains a list of tokens that the system can use to determine for what the image is used for. The exact meaning of the field depends on the individual catalog configuration but usually the following standard configuration is used:

Info-Value	Description
`searchable`	Image is a reference used for searching
`display`	Image is displayed in the UI
`searchable display`	Both
`display weight=3`	Display image with priority weight (recommended)
`display position=3`	Display image with priority position (deprecated, backwards compatibility only)

Order of display images

The order of display images can be controlled using two complementary mechanisms:

Explicit position field

Display images can be explicitly ordered using the position field in the image definition:

position is an integer value starting from 1
Only positive integers are allowed (1, 2, 3, ...)
Images with explicit positions are always displayed first, sorted by their position values
If multiple images have the same position value, they are sorted alphabetically by image_id
The position field can only be set for images that include the display token in their info field

Permission Requirements:

Only users with dataContributor or dataValidator roles can set or modify the position field
Other roles (including catalogAdmin) cannot specify positions and will receive an authorization error

Priority ordering via catalog configuration

Display image order can also be influenced by adding priority tokens to the info field, which work with the catalog configuration:

Syntax Update

The recommended syntax is now weight=x for better semantic clarity. The previous position=x syntax is deprecated and kept only for backwards compatibility.

Example: info="display weight=3"

Available syntax:

Recommended: weight=x (where x is a number) - Example: info="display weight=3"
- Use this syntax for all new implementations for better semantic clarity
Deprecated: position=x syntax is deprecated and kept only for backwards compatibility - Example: info="display position=3"
- This syntax still works but should be migrated to weight=x
- Only use this if updating legacy code that cannot be immediately migrated
If both weight=x and position=x are present, weight=x takes precedence

How it works:

Priority tokens are processed according to the catalog's image configuration rules
These work alongside the explicit position field to determine final display order
The exact behavior depends on the catalog's configuration settings
This method provides flexible ordering based on metadata patterns and business rules

note

There is a maximum number of images displayed in the UI. In the standard catalog configuration, the maximum is 5. If more than the maximum number of display images are defined for a part, the system selects images to be displayed with the following priority:

Explicitly positioned images (using the position field) are always prioritized and displayed first
- If there are more positioned images than the maximum, only the first ones (lowest position values) are shown
Images with catalog-configured priorities (using info field tokens like weight=x or deprecated position=x) fill remaining slots:
- These are processed according to the catalog's image configuration rules
- Images with higher priority values may be discarded first (depending on catalog configuration)
- For images with the same priority value, the system tries to maintain evenly spaced gaps
Non-positioned images fill any remaining slots, sorted by the catalog's default ordering rules

Creating or updating part images

POST /1/catalog/images

Multiple images can be created and/or updated in one call by specifying a list of definitions in images and a list of image files. The endpoint returns a list of ids of images, which have been created and a list of updated ids. The result contains also an error dictionary in case some images could not be created with corresponding error descriptions.

note

Unlike other upsert operations, this endpoint expects a request of type multipart/form-data because the image file data is attached to the search request payload.

note

This endpoint will respond with error code 503 when the catalog API is in maintenance mode.

Parameter	Value
`images`	List of image definitions
`files`	List of image file parts

images contains a list of image definitions. Each image definition must contain the following fields:

Parameter	Value	Required
`image_id`	Unique id of the image in the catalog	Yes
`part_id`	Id of the part type to which this image belongs	Yes
`info`	Meta data information to define the purpose of this image	Yes
`position`	Display order position (1, 2, 3...) for display images only	No

Permission Required

The position field can only be set by users with dataContributor or dataValidator roles. Other roles will receive an authorization error if they attempt to set this field.

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/images
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: multipart/form-data; boundary=549844d5-2a2e-4006-8ba9-6ca3423e3fa0
>
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0
> Content-Disposition: form-data; name="images"
> Content-Type: application/json
>
> [
>   {
>     "image_id": "image1",
>     "part_id": "part1",
>     "info": "searchable display"
>   },
>   {
>     "image_id": "image2",
>     "part_id": "part1",
>     "info": "display"
>   }
> ]
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0
> Content-Disposition: form-data; name="files"; filename="image1.jpg"
> Content-Type: image/jpeg
>
> <<your image binary content 1>>
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0
> Content-Disposition: form-data; name="files"; filename="image2.jpg"
> Content-Type: image/jpeg
>
> <<your image binary content 2>>
> --549844d5-2a2e-4006-8ba9-6ca3423e3fa0--
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "created": ["image1", "image2"],
<   "updated": [],
<   "errors": {}
< }

response = requests.post(
  'https://api.partium.io/1/catalog/images',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  files=[
    ('files', your_image_binary_content_1, 'image/jpeg'),
    ('files', your_image_binary_content_2, 'image/jpeg')
  ],
  data={
    "images": json.dumps([
      {
        "image_id": "image1",
        "part_id": "part1",
        "info": "searchable display"
      },
      {
        "image_id": "image2",
        "part_id": "part1",
        "info": "display"
      }
    ]
  }
)

let data = new FormData();
data.append('images', JSON.stringify([
  {
    "image_id": "image1",
    "part_id": "part1",
    "info": "searchable display"
  },
  {
    "image_id": "image2",
    "part_id": "part1",
    "info": "display"
  }
]));
data.append('files', new Blob(your_image_binary_content_1, {type: 'image/jpeg'}));
data.append('files', new Blob(your_image_binary_content_2, {type: 'image/jpeg'}));

fetch('https://api.partium.io/1/catalog/images', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: data,
}).then(res => {
  ...
});

note

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

Position Authorization Example

If a user without proper permissions tries to set a position, the API will respond with an error:

{
  "created": [],
  "updated": [],
  "errors": {
    "image1": ["image 'image1' only authorized roles can set position"]
  }
}

Deleting part images

DELETE /1/catalog/images

Multiple images can be deleted in one call by specifying a list of image ids. The endpoint returns a list of ids of images, which have been deleted. The result contains also an error dictionary in case some images could not be deleted with corresponding error descriptions.

note

This endpoint will respond with error code 503 when the catalog API is in maintenance mode.

🡢 See API Reference

HTTP
Python
JavaScript

> DELETE https://api.partium.io/1/catalog/images
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
> ["image1"]
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "deleted": ["image1"],
<   "errors": {}
< }

response = requests.delete(
  'https://api.partium.io/1/catalog/images',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json=["image1"]
)

fetch('https://api.partium.io/1/catalog/parts', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: ["image1"]
}).then(res => {
  ...
});

note

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

Listing part images

POST /1/catalog/images/list

Query a list of image descriptions. The list can be filtered by specifying a list of part_ids. A paging mechanism can be used to fetch more data if the number of results exceeds the paging limit.

Parameter	Value
`query.part_ids`	Optional list of part_ids to which the images belong
`paging.limit`	Maximum number of results returned by the endpoint
`paging.last_object_id`	Use this id to get the next page of results. The id is returned by a previous call to this endpoint
`projection`	Optional list of fields to be included in the response. Possible values: `part_id`, `info`, `position`

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/parts/list
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
>{
>  "paging": {
>    "limit": 10
>  },
>  "projection": ["part_id", "info"]
>}
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "result": [
<     {
<       "image_id": "image1",
<       "part_id": "part1",
<       "info": "searchable display"
<     },
<     {
<       "image_id": "image2",
<       "part_id": "part1",
<       "info": "display"
<     }
<   ],
<   "last_object_id": "unique_object_id",
<   "more_data": false
< }

response = requests.post(
  'https://api.partium.io/1/catalog/parts/list',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json={
    "paging": {
      "limit": 10
    },
    "projection": ["part_id", "info"]
  }
)

fetch('https://api.partium.io/1/catalog/parts/list', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "paging": {
      "limit": 10
    },
    "projection": ["part_id", "info"]
  }
}).then(res => {
  ...
});

note

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

more_data in the response is true indicates that there are more results to fetch. In that case use the returned last_object_id as a parameter for the next call to fetch the next page of results. Repeat this until more_data is false.

Fetching image descriptions by ID

POST /1/catalog/images/select

Fetch a list of image descriptions by specifying a list of image ids.

Parameter	Value
`image_ids`	List of ids of images to fetch
`projection`	Optional list of fields to be included in the response. Possible values: `part_id`, `info`, `position`

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/images/select
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
>{
>  "image_ids": ["image1", "image2"],
>  "projection": ["part_id", "info"]
>}
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< [
<   {
<     "image_id": "image1",
<     "part_id": "part1",
<     "info": "searchable display"
<   },
<   {
<     "image_id": "image2",
<     "part_id": "part1",
<     "info": "display"
<   }
< ]

response = requests.post(
  'https://api.partium.io/1/catalog/images/select',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json={
    "image_ids": ["image1", "image2"],
    "projection": ["part_id", "info"]
  }
)

fetch('https://api.partium.io/1/catalog/images/select', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "part_ids": ["image1", "image2"],
    "projection": ["part_id", "info"]
  }
}).then(res => {
  ...
});

note

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

Getting one image description

POST /1/catalog/images/{image_id}

Get the description of one image by specifying an image_id.

Parameter	Value
`image_id`	Unique ID of an image to fetch

🡢 See API Reference

HTTP
Python
JavaScript

> GET https://api.partium.io/1/catalog/image/image1
> Authorization: Bearer <<Your Access Token or API Key>>
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "image_id": "image1",
<   "part_id": "part1",
<   "info": "searchable display"
< }

response = requests.get(
  'https://api.partium.io/1/catalog/images/image1',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  }
)

fetch('https://api.partium.io/1/catalog/images/image1', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  }
}).then(res => {
  ...
});

note

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

Getting one image file

POST /1/catalog/images/{image_id}/original

Get the original image file that was uploaded of one image by specifying an image_id.

Parameter	Value
`image_id`	Unique ID of an image to fetch

🡢 See API Reference

HTTP
Python
JavaScript

> GET https://api.partium.io/1/catalog/image/image1/original
> Authorization: Bearer <<Your Access Token or API Key>>
>
< HTTP/1.1 200 OK
< Content-Type: image/jpeg
<
< <<binary_image_data>>

response = requests.get(
  'https://api.partium.io/1/catalog/images/image1/original',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  }
)

fetch('https://api.partium.io/1/catalog/images/image1/orignal', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  }
}).then(res => {
  ...
});

note

Replace image1 in the example above with the actual ID of the image file to be queried.

Replace <<Your Access Token or API Key>> with the preferred authentication method. See Authentication.

Order of display images​

Explicit position field​

Priority ordering via catalog configuration​

Creating or updating part images​

Deleting part images​

Listing part images​

Fetching image descriptions by ID​

Getting one image description​

Getting one image file​

Order of display images

Explicit position field

Priority ordering via catalog configuration

Creating or updating part images

Deleting part images

Listing part images

Fetching image descriptions by ID

Getting one image description

Getting one image file