Skip to main content
POST
Assign semantic IDs
Encode items into codes. Use this to backfill a catalog after fitting, to register new items as they go live, or to export semantic IDs into a ranker you already operate.

Response

Cold start

An item that was not in the catalog at fit time is still assignable, because the code is a function of content rather than of interaction history. Send it the moment it goes live and it is recommendable on the next POST /generate call.
The cold_start flag is worth logging. It lets you measure quality on items the tokenizer never saw, which is the number that tells you whether the fit generalized or memorized.
Cold-start assignment does not update the codebooks. If your catalog drifts far enough that new items cluster in regions the fit never covered, utilization will look fine while quality quietly degrades. Refit on distribution shift.

Determinism and stability

The same item content against the same tokenizer_id always returns the same codes. This is the point of keeping collaborative signal out of the quantizer input: an item’s identifier does not move as it gets popular. Codes are stable across POST /semantic-ids calls but not across refits. A new tokenizer_id is a new code space. Plan a reindex when you refit, and keep the old tokenizer live until the cutover completes.
Batches are capped at 1000 items per call. For a full catalog backfill, the tokenizer fit already assigns every item in catalog.uri, so you should not need to page through it manually.

Authorizations

Authorization
string
header
required

API key issued by Jean Technologies. Contact the team for access.

Body

application/json
tokenizer_id
string
required
Example:

"tok_9k2m"

items
object[]
required
Maximum array length: 1000

Response

Semantic IDs assigned

semantic_ids
object[]