API Documentation

Semantic taxonomy enrichment suggestions API

Reference details for the category suggestion service that returns a ranked list of relevant categories for a given seed product to enrich navigation and merchandising flows.

What is this?

A product-to-category intelligence endpoint that ranks the most relevant taxonomy nodes for a given product ID, making it easy to enrich mappings, improve browse discovery, and support assisted merchandising.

What it enables

Rapid taxonomy QA with ranked category paths and levels.
Automated enrichment of product-to-category mappings.
Navigation improvements through precise category routing.
Assisted merchandising for quicker assortment triage.

Endpoint

Example request URL

https://n8n.salnl.net/webhook/636def78-3472-4f51-b3f5-157a12c50ffa?pid=7212023

Request details

Query parameters

This endpoint returns a ranked list of categories based on the provided product ID, with optional filters for the number of results and category level.

pid (string | number, required): Seed product identifier used to generate category suggestions. Example: pid=7212023
limit (integer, optional): Maximum number of suggested categories to return (default: 5). Example: limit=10
cat_lvl (string, optional): Filter by category level or range. Examples: cat_lvl=2 or cat_lvl=2-4

Notes on cat_lvl

Single level: cat_lvl=2 → return only level 2 categories.
Range: cat_lvl=2-4 → return categories with level 2, 3, or 4.
If omitted, the endpoint may return categories across all available levels.

Examples

Request samples

Minimal request (uses default limit = 5)

https://n8n.salnl.net/webhook/636def78-3472-4f51-b3f5-157a12c50ffa?pid=7212023

Set limit explicitly

https://n8n.salnl.net/webhook/636def78-3472-4f51-b3f5-157a12c50ffa?pid=7212023&limit=10

Filter to a single category level

https://n8n.salnl.net/webhook/636def78-3472-4f51-b3f5-157a12c50ffa?pid=7212023&limit=10&cat_lvl=2

Filter to a range of levels

https://n8n.salnl.net/webhook/636def78-3472-4f51-b3f5-157a12c50ffa?pid=7212023&limit=10&cat_lvl=2-4

Response

Payload details

A successful response (200) returns a JSON array of category suggestions, sorted by relevance (highest score first).

score (number): Relevance score (higher = more relevant).
msdb_id (integer): Internal category identifier.
level (integer): Category depth/level in taxonomy.
url (string): Category URL.
title (string): Category display name.
path (string): Human-readable category path (breadcrumb-style).
expanded_keywords (string): Expanded keyword context used for semantic matching (for transparency/debugging).

Example response

[
  {
    "score": 0.69324654,
    "msdb_id": 70,
    "level": 2,
    "url": "https://www.maxi.rs/Bebi-svet/Vlazhne-maramice/c/1508",
    "title": "Vlazhne maramice",
    "path": "Bebi-svet > Vlazhne-maramice",
    "expanded_keywords": "vlažne bebe higijenske čišćenje pelene beba putne antibakterijske ekološke mekane"
  }
]

Error handling

Recommended behaviors

400 Bad Request: missing or invalid pid, invalid limit, invalid cat_lvl format.
404 Not Found: product not found for pid (if implemented).
500 Internal Server Error: unexpected server error.