Embed

POST /models/{model_id}/embed

No prediction, just the representation. Send a history and get back the vector the model would have decoded from.

This is the endpoint for teams who already own a ranker and want a better feature rather than a replacement system. It is also how you get behavioral similarity between two people without routing through items.

curl

curl https://api.jeantechnologies.com/v1/models/jean-rec-1/embed \
  -H "Authorization: Bearer $JEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "history": ["sku_310", "sku_884", "sku_771"]
  }'

Python

vec = requests.post(
    "https://api.jeantechnologies.com/v1/models/jean-rec-1/embed",
    headers={"Authorization": f"Bearer {os.environ['JEAN_API_KEY']}"},
    json={"history": ["sku_310", "sku_884", "sku_771"]},
).json()["embeddings"][0]["vector"]

TypeScript

const res = await fetch(
  "https://api.jeantechnologies.com/v1/models/jean-rec-1/embed",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.JEAN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ history: ["sku_310", "sku_884", "sku_771"] }),
  },
);
const { embeddings } = await res.json();

Body

Field	Type	Default	Notes
history	string[] | object[]	required	One history, or a batch. Same shape as /predict.
batch	object[]		Up to 256 histories per call, each with an optional key echoed back.
normalize	boolean	true	L2-normalize, so a dot product is a cosine.

Response

{
  "embeddings": [
    {
      "key": "u_18",
      "vector": [0.021, -0.114, 0.087, "..."],
      "dim": 1024
    }
  ],
  "model": "jean-rec-1",
  "version": "1.0.0",
  "normalized": true
}

What the vector is

It is a state, not a profile. It encodes where this person is in behavior space given the sequence you sent, so it moves as the sequence moves. Two people with identical vectors are predicted to act the same next, which is not the same as being similar people.

That distinction matters if you plan to store them. Re-embed on new interactions rather than computing a vector once at signup and treating it as an attribute of the person.

warning

Vectors are comparable within one model and version only. A version bump moves the space, so a stored index has to be rebuilt. Compare version on read before you compare vectors.

Uses

Use	How
Feature in your ranker	Concatenate onto your existing feature vector
Behavioral similarity	Cosine between two histories, with normalize: true
Segmentation	Cluster over a population sample, see Simulation
Cold-start users	Embed the session so far, even a few events in

note

Item vectors are not exposed here. An item's representation is its semantic ID, which is discrete by design, and POST /semantic-ids is where you get it.