Item Catalog

Item Ids

An item has to have at least an ID and optionally additional key/value properties.

Databases can be configured with various types of item IDs, such as UUIDs or integers. When creating the database above, we selected uint32, which stands for 32-bit (4-bytes) unsigned integers.

See the Flexible Identifiers documentation to find the available types of item IDs.

Like in a SQL database, properties must be defined before you can insert items or users with these properties.

Item Properties

Items meta-data is called “properties”. Using rich properties gives two advantages:

  • it improves the recommendations, especially for both cold-start problems where the algorithm relies only on properties (such as Semantic Graph Embedding from genres and tags, or Deep Content Extraction from text and images)
  • it enables to dynamically filter the recommendations on items satisfying certain criteria (such as a price smaller than a threshold given at runtime, or a geo-location close to given coordinates, see Filtering on Item Property)

Items are abstract key/value maps that follow a schema you specify by creating properties. Values are strongly typed (e.g., floating points, integers, categorical strings) and can be repeated.

See the Property Types documentation to find the available property types and filters.

The endpoint POST-items-properties/ is used to create items property. In this example, we consider a property 'price' which is a non-repeated float, and a property 'tags', which is a repeated Unicode string of (up to) 20 characters.

Curl Request
Copied to clipboard!
 $ curl -s \  -H "Authorization: Bearer $JWT_TOKEN" \  -H "Content-Type: application/json" \  -d '{"property_name": "price", "value_type": "float", "repeated": false}'$ curl -s \  -H "Authorization: Bearer $JWT_TOKEN" \  -H "Content-Type: application/json" \  -d '{"property_name": "tags", "value_type": "unicode20", "repeated": true}'

You can now create the items of your catalog using the endpoint PUT items-bulk/.

Curl Request
Copied to clipboard!
$ curl -X PUT -s \  -H "Authorization: Bearer $JWT_TOKEN" \  -H "Content-Type: application/json" \  -d '{ \    "items": [ \      {"item_id": "1", "price": 9.99, "tags": ["family", "sci-fi"]}, \      ... \      {"item_id": "999", "price": 4.49, "tags": ["family"]} \    ]}'

When sending thousands of items or more, it is strongly recommended to split into multiple requests. The optimal size of the batch depends on the amount of data that is sent and on the encoding. A batch size of 500 should be a good starting point.

Images as a property

Using images for product recommendations plays a critical role in enhancing user engagement, improving the shopping experience, and increasing the chances of conversion. Images provide a comprehensive understanding of the product at first glance, enriching the information that textual descriptions provide, and often sway users' purchasing decisions. In our Recommendation API, product images can be set up as part of the item properties under the domain of 'image'. These images contribute significantly to Deep Content Extraction, wherein advanced algorithms are leveraged to understand the semantic meaning and contextual relevance of the content. By extracting important visual features from the images, our API can provide even more refined and personalized recommendations based on visual similarity and user preference patterns.

To set up images in our API, you must define a property within the item properties where the 'value_type' is specified as 'image'. You'll need to follow the API's specifications regarding the maximum size and supported formats, ensuring optimal compatibility and performance. The provided image URL will be used by the Recommendation API to fetch and process the image, further enhancing the recommendation process. It's important to remember to provide high-quality images, as clearer images lead to more accurate feature extraction and thus more personalized and effective recommendations.

Text as a property

Providing comprehensive descriptions and textual data for your products significantly enhances the efficiency and effectiveness of product recommendations. Descriptive texts offer a detailed perspective of a product, enabling a deeper understanding of its features, usage, and relevance to the user. This data can include detailed product descriptions, user reviews, or any other textual information related to the product.

In our Recommendation API, such textual data falls under the domain of 'Long text', contributing to Deep Content Extraction. Deep Content Extraction utilizes sophisticated Natural Language Processing (NLP) algorithms to analyze and understand the contextual and semantic meaning of the text. It enables the extraction of essential features and keywords from the text, contributing to the creation of a semantic graph.

To set up these textual descriptions in our API, you need to define a property within the item properties where the 'value_type' is specified as 'Long text'. The input text can be the product description or any other relevant textual data you want the Recommendation API to process. The Deep Content Extraction process not only helps in generating more accurate and context-aware recommendations but also contributes to personalized experiences. By understanding the semantics in product descriptions, it can better match products to user preferences, needs, and search contexts, thereby improving user satisfaction and potentially increasing conversion rates.

Tags as a property

Tags are crucial elements when uploading product catalogs to our Recommendation API, serving as concise identifiers that encapsulate the core attributes of a product. These could include product categories, color, style, material, or any specific feature that could distinguish a product. Properly cleaned and well-defined tags contribute significantly towards the user's search and discovery process, allowing for streamlined navigation and more accurate query results.

In our Recommendation API, these tags fall under the 'Categorical' domain and play a pivotal role in the Semantic Graph Embedding approach. This approach utilizes machine learning techniques to convert categorical data into dense vectors in a high-dimensional space, effectively encapsulating the semantic relationships between different products. The tags are transformed into a graph structure where similar products are clustered together based on the semantic similarity of their tags.

To incorporate tags, you need to define a property within the item properties where the 'value_type' is defined as 'Categorical'. The list of tags associated with each product should be provided as a part of the product data. Remember, the cleaner and more specific your tags are, the more accurately they can be processed by our Semantic Graph Embedding approach.

This process facilitates more nuanced and contextually relevant recommendations. It allows our Recommendation API to suggest items not only based on the individual product's attributes but also considering the implicit relationships between different products. This further refines the recommendation quality, leading to a more personalized user experience and improved user engagement.

Creating a Property

once your first Database created, you can create new properties directly from your dashboard in the `Item Property` tab.

Then click on "Create Property" to access the following modal.

From there on, define your property by entering the name, type and lenght.

For more information about item properties, please refer to the list of property types below.

Property Types


  • Domains with = in “Filters” means they support the eq, neq, in, notin operators in recommendations filters
  • Domains with < in “Filters” means they support the lt, gt operators in recommendations filters
  • Domains with both = and < in “Filters” also support the lte, gte operators in recommendations filters
  • Categorical domains contribute to Semantic Graph Embedding
  • Scalar domains contribute to Shallow Content Extraction
  • Long text and image domains contribute to Deep Content Extraction
  • In integer domains, valid <NBITS> are 8, 16, 32 and 64
  • In float domains, valid <NBITS> are 32 and 64
  • In string and bytes domains, <NCHARS> encodes the maximum size. It defaults to the maximum of 255 chars

Get started with Crossing Minds recommendation API

Crossing Minds Recommendation API is the easiest way to integrate personalized recommendation to your website & mobile apps

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
We use cookies (and other similar technologies) to collect data in order to improve our site. You have the option to opt-in or opt-out of certain cookie tracking technologies.To do so, click here.


API Documentation Center,
please wait a bit...