Items Data and Properties

List All Item-Properties

GET items-properties/

Note

Authorized Roles: root, manager, backend, frontend

Get all item-properties for the current database.

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• properties (list-of-object) –

  All properties

  Inner fields

  • property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved

  • value_type (string) – [max-length: 10] Property type [see Property Types]

  • repeated (bool) – Whether the property has many values

  • metadata (json-value) – Metadata, unvalidated JSON

EXAMPLE RESPONSE

  {
      "properties": [
          {
              "property_name": "price",
              "value_type": "float32",
              "repeated": false,
              "metadata": {}
          },
          {
              "property_name": "tags",
              "value_type": "unicode32",
              "repeated": true,
              "metadata": {}
          },
          {
              "property_name": "genres",
              "value_type": "unicode16",
              "repeated": true,
              "metadata": {}
          }
      ]
  }

Create New Item-Property

POST items-properties/

Note

Authorized Roles: root, manager, backend

Create a new item-property, identified by property_name (case-insensitive).

Request JSON Object

• property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved

• value_type (string) – [max-length: 10] Property type [see Property Types]

• repeated (bool) – Optional. Whether the property has many values

• metadata (json-value) – Optional. Metadata, unvalidated JSON

EXAMPLE QUERY BODY

  {
      "property_name": "price",
      "value_type": "float32",
      "repeated": false,
      "metadata": {"flag": true}
  }

Errors:

• DuplicatedError with error name DUPLICATED_ITEM_PROPERTY if an item property with the same name already exists

• WrongData with error name WRONG_DATA_TYPE if value_type is invalid

Get One Item-Property

GET items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Get one item-property given its property_name.

Response JSON Object

• property_name (string) – [max-length: 64] Property name. Only alphanumeric characters, dots, underscores or hyphens are allowed. The names ‘item_id’ and ‘user_id’ are reserved

• value_type (string) – [max-length: 10] Property type [see Property Types]

• repeated (bool) – Optional. Whether the property has many values

• metadata (json-value) – Optional. Metadata, unvalidated JSON

EXAMPLE RESPONSE

  {
      "property_name": "price",
      "value_type": "float32",
      "repeated": false,
      "metadata": {}
  }

Errors:

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if the property name cannot be found

Delete Item-Property

DELETE items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Delete an item-property given by its name

Errors:

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if the property name cannot be found

• WrongData with error name ITEM_PROPERTY_FOUND_IN_SCENARIO if the property is being used in a scenario

[Internal] Partial Update Item-Property

PATCH items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend

Deep partial update of the item-property’s metadata.

Request JSON Object

• metadata (json-value) – Optional. Metadata, unvalidated JSON

• preserve (bool) – Optional. whether to use JSON_MERGE_PRESERVE instead of JSON_MERGE_PATCH

EXAMPLE QUERY BODY

  {
      "metadata": {"new_flag": true}
  }

Errors:

• NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if the property name cannot be found

Get Properties of One Item

GET items/<str:item_id>/properties/

Note

Authorized Roles: root, manager, backend, frontend

Get property values of one item given its ID.

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• item (object) – Item data

EXAMPLE RESPONSE

  {
      "item": {
          "item_id": "123e4567-e89b-12d3-a456-426614174000",
          "tags": ["family", "sci-fi"],
          "genres": ["drama", "comedy"],
          "price": 9.99
      }
  }

Errors:

• NotFoundError with error name ITEM_NOT_FOUND if no item with the given item_id can be found

Create or Replace Properties of One Item

PUT items/<str:item_id>/properties/

Note

Authorized Roles: root, manager, backend

Create property values for one item, or replace them if the item_id already exists.

All property types need to be defined beforehand, see Items and Users Properties.

Note that item_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

• item (object) – Item data

• wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of items properties values is done beforehand, the background task may fail silently.

EXAMPLE QUERY BODY

  {
      "item": {
          "tags": ["family", "sci-fi"],
          "genres": ["drama", "comedy"],
          "price": 9.99
      }
  }

Errors:

• WrongData with error name WRONG_DATA_TYPE if the properties are invalid

Partial Update Properties of One Item

PATCH items/<str:item_id>/properties/

Note

Authorized Roles: root, manager, backend

Partially update some property values of one item. The properties that are not listed in the request body will be left unchanged. The list of values given for repeated properties will replace (not append) the previous list of values.

Use the body parameter create_if_missing to control whether an error should be returned or a new item should be created when the item_id does not already exist.

All property types need to be defined beforehand, see Items and Users Properties.

Note that item_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

• item (object) – Item data

• create_if_missing (bool) – Optional. Create item that does not exist

EXAMPLE QUERY BODY

  {
      "item": {
          "tags": ["family", "sci-fi"],
          "genres": ["drama", "comedy"],
          "price": 9.99
      },
      "create_if_missing": false
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• item_created (bool) – Indicates if the item was created

• item_modified (bool) – Indicates if the item was modified

EXAMPLE RESPONSE

  {
      "item_created": true,
      "item_modified": false
  }

Errors:

• WrongData with error name WRONG_DATA_TYPE if the properties are invalid

• NotFoundError only when create_if_missing=False with error name ITEM_NOT_FOUND if no item with the given item_id can be found

Delete Properties of One Item

DELETE items/<str:item_id>/properties/

Note

Authorized Roles: root, manager, backend

Delete the property values of one item given its ID. Ratings and interactions are not deleted.

This endpoint is not commonly used. Note that to stop recommending an item, it is preferable to perform a partial update on a status property (or equivalent), and filter out the unwanted item using Filtering on Item Property. This allows the recommendation model to keep learning patterns of the previously available item.

This endpoint is typically used only after some developer mistake, when the property values of an item shouldn’t have been set.

Create or Replace Properties of Many Items in Bulk

PUT items-bulk/properties/

Note

Authorized Roles: root, manager, backend

Create property values for many items in bulk, or replace the ones for which the item_id already exist.

All property types need to be defined beforehand, see Items and Users Properties.

Note that item_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

• items (object-array) –

  (additional fields may be present) Items values

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• items_m2m (list-of-object) –

  Optional. Items repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

  Inner fields

  • name (string) – [max-length: 64] M2M name

  • array (object-array) – M2M array

    Inner fields

    • item_index (uint32) – Item index (0-based)

    • value_id (any) – M2M related object ID

• wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of items properties values is done beforehand, the background task may fail silently.

EXAMPLE QUERY BODY (JSON client)

  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ],
      "wait_for_completion": true
  }

EXAMPLE QUERY BODY (array-optimized format for binary client)

  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49
          }
      ],
      "items_m2m": [
          {
              "name": "tags",
              "array": [
                  {"item_index": 0, "value_id": "family"},
                  {"item_index": 0, "value_id": "sci-fi"},
                  {"item_index": 1, "value_id": "family"}
              ]
          },
          {
              "name": "genres",
              "array": [
                  {"item_index": 0, "value_id": "drama"},
                  {"item_index": 0, "value_id": "comedy"},
                  {"item_index": 1, "value_id": "thriller"}
              ]
          }
      ]
  }

Note that we represent the array-optimized using JSON for readability, but you should use a binary array instead

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• n_created (int) – Number of items created (only when wait_for_completion=true)

• n_modified (int) – Number of items modified (only when wait_for_completion=true)

• ml_task_id (string) – Optional. ml_new_items Background Task ID. Only when items are created.

EXAMPLE RESPONSE

{
    "n_created": 10,
    "n_modified": 2,
    "ml_task_id": "4xBBB6qkqDbGdlyYRAjF"
}

Errors:

• WrongData with error name WRONG_DATA_TYPE if the properties are invalid

• DuplicatedError with error name DUPLICATED_ITEM_ID if an item_id occurs multiple times in the same request

List Properties of All Items in Bulk

GET items-bulk/properties/

Note

Authorized Roles: root, manager, backend

Get property values of multiple items by page. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Note that the array-optimized format items_m2m for repeated values is used only for binary clients. Otherwise (e.g. JSON client), the repeated values are formatted as lists in each individual items.

Query Parameters

• amt (int) – Optional. [max: 500] Maximum amount of items returned, by default is 300

• cursor (string) – Optional. Pagination cursor, typically from the next_cursor value from the previous response

• properties (list-of-string) – Optional. Names of properties to fetch (by default, all properties are fetched)

• filters (list-of-object) –

  Optional. Filter on item properties [see Filtering on Item Property]

  Inner fields

  • property_name (string) – Item-property name

  • op (enum) – choices (case insensitive): [eq, lt, lte, gt, gte, in, empty, notempty, neq, notin, ftsearch] Filter Operator

  • value (json-value) – Filter Value

EXAMPLE QUERY PARAMS

  ?amt=100&cursor=Q21vU1pHb1FjSEp...

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items (object-array) –

  (additional fields may be present) Items values

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• items_m2m (list-of-object) –

  Items repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

  Inner fields

  • name (string) – [max-length: 64] M2M name

  • array (object-array) – M2M array

    Inner fields

    • item_index (uint32) – Item index (0-based)

    • value_id (any) – M2M related object ID

• has_next (bool) – Indicates whether or not there are more items to request

• next_cursor (string) – Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE (JSON client)

  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ],
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp..."
  }

Partial Update Properties of Many Items in Bulk

PATCH items-bulk/properties/

Note

Authorized Roles: root, manager, backend

Partially update some property values of many items. The properties that are not listed in the request body will be left unchanged. The list of values given for repeated properties will replace (not append) the previous list of values.

Use the body parameter create_if_missing to control whether an error should be returned or new items should be created when the item_id does not already exist.

All property types need to be defined beforehand, see Items and Users Properties.

Note that item_id cannot be a “null” or “falsy” value, such as empty string or 0.

Request JSON Object

• items (object-array) –

  (additional fields may be present) Items values

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• items_m2m (list-of-object) –

  Optional. Items repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

  Inner fields

  • name (string) – [max-length: 64] M2M name

  • array (object-array) – M2M array

    Inner fields

    • item_index (uint32) – Item index (0-based)

    • value_id (any) – M2M related object ID

• wait_for_completion (bool) – Optional. Default is true to wait for completion and respond with 200 OK. Set to false to respond immediately with 202 Accepted after validation, and process asynchronously in the background. The background process may take 30 seconds to start, and there is no way to get notified when the process is complete. No validation of items properties values is done beforehand, the background task may fail silently.

• create_if_missing (bool) – Optional. Create items that do not exist

EXAMPLE QUERY BODY (JSON client)

  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ],
      "create_if_missing": false
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• n_created (int) – Number of items created (only when wait_for_completion=true)

• n_modified (int) – Number of items modified (only when wait_for_completion=true)

• ml_task_id (string) – Optional. ml_new_items Background Task ID. Only when items are created.

EXAMPLE RESPONSE

{
    "n_created": 17,
    "n_modified": 5,
    "ml_task_id": "4xBBB6qkqDbGdlyYRAjF"
}

Errors:

• WrongData with error name WRONG_DATA_TYPE if the properties are invalid

• DuplicatedError with error name DUPLICATED_ITEM_ID if an item_id occurs multiple times in the same request

• NotFoundError only when create_if_missing=False with error name ITEM_NOT_FOUND if at least one item with the given item_id cannot be found

Delete Properties of Many Items in Bulk

DELETE items-bulk/properties/

Note

Authorized Roles: root, manager, backend

Delete the property values of many items in bulk. Ratings and interactions are not deleted.

This endpoint is not commonly used. Note that to stop recommending some items, it is preferable to perform a bulk partial update on a status property (or equivalent), and filter out the unwanted items using Filtering on Item Property. This allows the recommendation model to keep learning patterns of previously available items.

This endpoint is typically used only after some developer mistake, when the property values of some items shouldn’t have been set.

Request JSON Object

• items_id (ID-array) – Items IDs

EXAMPLE QUERY BODY

  {
      "items_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ]
  }

List Properties of Many Items by ID

POST items-bulk/properties/list/

Note

Authorized Roles: root, manager, backend, frontend

Get property values of multiple items given their IDs. Note that the HTTP verb is POST so that items ids can be sent in the body, but the endpoint is stateless as GET.

The item properties in the response are not aligned with the input. In particular this endpoint does not respond with 404 if any item in missing. Instead, the missing items are simply not present in the response.

Note that the array-optimized format items_m2m for repeated values is used only for binary clients. Otherwise (e.g. JSON client), the repeated values are formatted as lists in each individual items.

Request JSON Object

• items_id (ID-array) – Items IDs

• properties (list-of-string) – Optional. Names of properties to fetch (by default, all properties are fetched)

EXAMPLE QUERY BODY

  {
      "items_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ],
      "properties": ["price", "tags", "genres"]
  }

Response JSON Object

• warnings (list-of-string) – Optional. List of warnings

• items (object-array) –

  (additional fields may be present) Items values

  Inner fields

  • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

• items_m2m (list-of-object) –

  Items repeated values in array-optimized many-to-many format for binary clients [see Repeated Values]

  Inner fields

  • name (string) – [max-length: 64] M2M name

  • array (object-array) – M2M array

    Inner fields

    • item_index (uint32) – Item index (0-based)

    • value_id (any) – M2M related object ID

EXAMPLE RESPONSE (JSON client)

  {
      "items": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "price": 9.99,
              "tags": ["family", "sci-fi"],
              "genres": ["drama", "comedy"]
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "price": 4.49,
              "tags": ["family"],
              "genres": ["thriller"]
          }
      ]
  }

[Deprecated] Get Properties of One Item

GET items/<str:item_id>/

Note

Authorized Roles: root, manager, backend, frontend

Warning

DEPRECATED

See GET items/<str:item_id>/properties/

[Deprecated] Create or Replace One Item

PUT items/<str:item_id>/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PUT items/<str:item_id>/properties/

[Deprecated] Partial Update One Item

PATCH items/<str:item_id>/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PATCH items/<str:item_id>/properties/

[Deprecated] Delete One Item

DELETE items/<str:item_id>/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See DELETE items/<str:item_id>/properties/

[Deprecated] Create or Replace Many Items in Bulk

PUT items-bulk/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PUT items-bulk/properties/

[Deprecated] List Properties of All Items in Bulk

GET items-bulk/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See GET items-bulk/properties/

[Deprecated] Partial Update Many Items in Bulk

PATCH items-bulk/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See PATCH items-bulk/properties/

[Deprecated] Delete Many Items in Bulk

DELETE items-bulk/

Note

Authorized Roles: root, manager, backend

Warning

DEPRECATED

See DELETE items-bulk/properties/

[Deprecated] List Properties of Many Items by ID

POST items-bulk/list/

Note

Authorized Roles: root, manager, backend, frontend

Warning

DEPRECATED

See POST items-bulk/properties/list/