> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jeanmemory.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assign semantic IDs

> Assign semantic IDs to items against a fitted tokenizer.

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.

<CodeGroup>
  ```bash curl theme={"dark"}
  curl https://api.jeantechnologies.com/v1/semantic-ids \
    -H "Authorization: Bearer $JEAN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "tokenizer_id": "tok_9k2m",
      "items": [
        {
          "item_id": "sku_771",
          "title": "Merino crew socks",
          "description": "Mid-weight, charcoal.",
          "image_url": "https://acme.com/771.jpg"
        }
      ]
    }'
  ```

  ```python Python theme={"dark"}
  res = requests.post(
      "https://api.jeantechnologies.com/v1/semantic-ids",
      headers={"Authorization": f"Bearer {os.environ['JEAN_API_KEY']}"},
      json={
          "tokenizer_id": "tok_9k2m",
          "items": [
              {
                  "item_id": "sku_771",
                  "title": "Merino crew socks",
                  "description": "Mid-weight, charcoal.",
              }
          ],
      },
  ).json()
  ```

  ```ts TypeScript theme={"dark"}
  const res = await fetch("https://api.jeantechnologies.com/v1/semantic-ids", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JEAN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      tokenizer_id: "tok_9k2m",
      items: [
        {
          item_id: "sku_771",
          title: "Merino crew socks",
          description: "Mid-weight, charcoal.",
        },
      ],
    }),
  });
  const { semantic_ids } = await res.json();
  ```
</CodeGroup>

## Response

```json theme={"dark"}
{
  "semantic_ids": [
    {
      "item_id": "sku_771",
      "codes": [1487, 302, 91, 12],
      "tokens": "<sid_0_1487><sid_1_302><sid_2_91><sid_3_12>",
      "cold_start": false,
      "collision_suffix": null
    }
  ]
}
```

## 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.

```json theme={"dark"}
{
  "item_id": "sku_new",
  "codes": [1487, 88, 405, 3],
  "tokens": "<sid_0_1487><sid_1_88><sid_2_405><sid_3_3>",
  "cold_start": true
}
```

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.

<Warning>
  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.
</Warning>

## 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.

<Note>
  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.
</Note>


## OpenAPI

````yaml POST /semantic-ids
openapi: 3.1.0
info:
  title: Jean Technologies API
  version: 1.0.0
  description: >-
    Foundation models of human behavior. Fit a semantic ID tokenizer on your
    catalog, generate recommendations over it, and send outcomes back.
servers:
  - url: https://api.jeantechnologies.com/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /semantic-ids:
    post:
      tags:
        - Semantic IDs
      summary: Assign semantic IDs
      description: >-
        Assign semantic IDs to items against an existing tokenizer. Items absent
        from the catalog the tokenizer was fit on are assigned from their
        content alone and flagged `cold_start: true`, so a brand-new item is
        recommendable immediately. No refit is needed to add items. Refit when
        the catalog's distribution shifts, not when it grows.
      operationId: assignSemanticIds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignSemanticIdsRequest'
      responses:
        '200':
          description: Semantic IDs assigned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignSemanticIdsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    AssignSemanticIdsRequest:
      type: object
      required:
        - tokenizer_id
        - items
      properties:
        tokenizer_id:
          type: string
          example: tok_9k2m
        items:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/ItemInput'
    AssignSemanticIdsResponse:
      type: object
      properties:
        semantic_ids:
          type: array
          items:
            $ref: '#/components/schemas/SemanticId'
    ItemInput:
      type: object
      required:
        - item_id
      properties:
        item_id:
          type: string
          example: sku_771
        title:
          type: string
          example: Merino crew socks
        description:
          type: string
          example: Mid-weight, charcoal.
        image_url:
          type: string
          example: https://acme.com/771.jpg
        attributes:
          type: object
          additionalProperties: true
          description: >-
            Catalog attributes such as brand, category, or price. Encoded
            alongside the text.
          example:
            brand: Acme
            category: hosiery
    SemanticId:
      type: object
      properties:
        item_id:
          type: string
          example: sku_771
        codes:
          type: array
          items:
            type: integer
          description: One code per level, coarse to fine.
          example:
            - 1487
            - 302
            - 91
            - 12
        tokens:
          type: string
          description: The codes rendered as vocabulary tokens.
          example: <sid_0_1487><sid_1_302><sid_2_91><sid_3_12>
        cold_start:
          type: boolean
          description: True if the item was not in the catalog the tokenizer was fit on.
          example: false
        collision_suffix:
          type: integer
          nullable: true
          description: >-
            Set when another item quantized to identical codes, so the pair
            stays distinguishable.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: invalid_request
            message:
              type: string
              example: Field 'domain' is required.
            details:
              type: object
              additionalProperties: true
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key issued by Jean Technologies. Contact the team for access.

````