Attributes

This section describes how to manage attributes for the ontology in the Catalog API.

Creating or updating attributes

POST /1/catalog/attributes

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

Request body field	Value
`attribute_id`	Unique id of the attribute in the catalog
`type`	Type of the attribute ("text" or "enum")
`name`	Name of the attribute. Dictionary with language-specific values. This name will be displayed in the UI
`searchable`	Boolean value indicating if the attribute is searchable.
`filterable`	Boolean value indicating if the attribute is filterable.
`visibility`	Determines which user roles can see the corresponding attribute values in the app. Possible values are one of: "factoryWorker", "admin", "superAdmin", or "csa"
`org_visibility`	Determines whether the attribute values are visible for the parent organization only or for sub-organizations as well ("parent" or "sub")
`labels`	Defines which of the pre-defined standard attribute label(s) should be conceptually associated with the values provided for this attribute. See Attribute labels for more details.
`per_org_values`	Boolean indicating whether the values belong to a specific organization. When a part has a value for an attribute with `per_org_values` set to true, an organization must be specified by name (see this example).
`default_value`	Optional object. Specifies the default value for a per‑org attribute. Only applicable when `per_org_values` is true. If provided, this value will be used as the default when no organization‑specific override is set, and it will affect search and filtering accordingly. The value should be provided as a dictionary with language keys and string values (e.g. `{"en": "default text", "de": "standardtext"}`). For more examples, see the Part Structure Examples.

note

Default Value for Per‑Org Attributes

When creating or updating an attribute that is organization‑specific (i.e. with per_org_values set to true), you can provide an optional default_value. This value (a string) will be used as the attribute's default if no organization‑specific override is supplied, and it is what users will see when no override exists. Furthermore, search operations will consider entities that rely on this default during filtering and matching. To override the default, provide an updated value for the attribute in the corresponding update call.

note

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

🡢 See Structure of attributes

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/attributes
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
> [
>   {
>     "attribute_id": "manufacturer",
>     "type": "enum",
>     "name": {
>       "en": "Manufacturer",
>       "de": "Hersteller"
>     },
>     "searchable": true,
>     "filterable": true,
>     "visibility": "admin",
>     "org_visibility": "parent",
>     "per_org_values": false
>   },
>   {
>     "attribute_id": "delivery_time",
>     "type": "text",
>     "name": {
>       "en": "Delivery Time",
>       "de": "Lieferzeit"
>     },
>     "searchable": true,
>     "filterable": true,
>     "visibility": "admin",
>     "org_visibility": "sub",
>     "per_org_values": true,
>     "default_value": {
>       "en": "Standard Delivery Time",
>       "de": "Standard Lieferzeit"
>     }
>   }
> ]
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "created": ["manufacturer", "delivery_time"],
<   "updated": [],
<   "errors": {}
< }

response = requests.post(
  'https://api.partium.io/1/catalog/attributes',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
    'Content-Type': 'application/json'
  },
  json=[
    {
      "attribute_id": "manufacturer",
      "type": "enum",
      "name": {
          "en": "Manufacturer",
          "de": "Hersteller"
      },
      "searchable": True,
      "filterable": True,
      "visibility": "admin",
      "org_visibility": "parent",
      "per_org_values": False
    },
    {
      "attribute_id": "delivery_time",
      "type": "text",
      "name": {
          "en": "Delivery Time",
          "de": "Lieferzeit"
      },
      "searchable": True,
      "filterable": True,
      "visibility": "admin",
      "org_visibility": "sub",
      "per_org_values": True,
      "default_value": {
          "en": "Standard Delivery Time",
          "de": "Standard Lieferzeit"
      }
    }
  ]
)

fetch('https://api.partium.io/1/catalog/attributes', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      "attribute_id": "manufacturer",
      "type": "enum",
      "name": {
          "en": "Manufacturer",
          "de": "Hersteller"
      },
      "searchable": true,
      "filterable": true,
      "visibility": "admin",
      "org_visibility": "parent",
      "per_org_values": false
    },
    {
      "attribute_id": "delivery_time",
      "type": "text",
      "name": {
          "en": "Delivery Time",
          "de": "Lieferzeit"
      },
      "searchable": true,
      "filterable": true,
      "visibility": "admin",
      "org_visibility": "sub",
      "per_org_values": true,
      "default_value": {
          "en": "Standard Delivery Time",
          "de": "Standard Lieferzeit"
      }
    }
  ])
}).then(res => {
  ...
});

note

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

Deleting attributes

DELETE /1/catalog/attributes

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

note

All attribute entries of all part types that contain a reference to the attribute definition must be removed before an attribute can be deleted.

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/attributes
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
> ["attribute1"]
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "deleted": ["attribute1"],
<   "errors": {}
< }

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

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

note

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

Listing attributes

POST /1/catalog/attributes/list

Query a list of attributes. A paging mechanism can be used to fetch more data if the number of results exceeds the paging limit.

Parameter	Value
`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: `name`, `type`, `searchable`, `filterable`, `visibility`, `org_visibility`

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/attributes/list
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
> {
>   "paging": {
>     "limit": 10
>   },
>   "projection": ["name", "type"]
> }
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< {
<   "result": [
<     {
>       "attribute_id": "manufacturer",
>       "type": "enum",
>       "name": {
>         "en": "Manufacturer",
>         "de": "Hersteller"
>       },
<     },
<     {
>       "attribute_id": "manufacturer_id",
>       "type": "enum",
>       "name": {
>         "en": "Manufacturer ID",
>         "de": "Hersteller ID"
>       },
>     }
<   ],
<   "last_object_id": "unique_object_id",
<   "more_data": false
< }

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

fetch('https://api.partium.io/1/catalog/attributes/list', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "paging": {
      "limit": 10
    },
    "projection": ["name", "type"]
  }
}).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 attributes by ID

POST /1/catalog/attributes/select

Fetch a list of attributes by specifying a list of attribute ids.

Parameter	Value
`attribute_ids`	List of ids of attributes to fetch
`projection`	Optional list of fields to be included in the response. Possible values: `name`, `type`, `searchable`, `filterable`, `visibility`, `org_visibility`

🡢 See API Reference

HTTP
Python
JavaScript

> POST https://api.partium.io/1/catalog/attributes/select
> Authorization: Bearer <<Your Access Token or API Key>>
> Content-Type: application/json
>
> {
>   "attribute_ids": ["manufacturer", "manufacturer_id"],
>   "projection": ["name", "type"]
> }
>
< HTTP/1.1 200 OK
< Content-Type: application/json
<
< [
<   {
<     "attribute_id": "manufacturer",
<     "name": {"en": "Manufacturer", "de": "Hersteller"},
<     "type": "enum"
<   },
<   {
<     "attribute_id": "manufacturer_id",
<     "name": {"en": "Manufacturer ID", "de": "Hersteller ID"},
<     "type": "enum"
<   }
< ]

response = requests.post(
  'https://api.partium.io/1/catalog/attributes/select',
  headers={
    'Authorization': 'Bearer <<Your Access Token or API Key>>',
  },
  json={
    "attribute_ids": ["manufacturer", "manufacturer_id"],
    "projection": ["name", "type"]
  }
)

fetch('https://api.partium.io/1/catalog/attributes/select', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <<Your Access Token or API Key>>',
  },
  body: {
    "attribute_ids": ["manufacturer", "manufacturer_id"],
    "projection": ["name", "type"]
  }
}).then(res => {
  ...
});

note

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

Creating or updating attributes​

Deleting attributes​

Listing attributes​

Fetching attributes by ID​

Creating or updating attributes

Deleting attributes

Listing attributes

Fetching attributes by ID