Embeddings and specialised endpoints

## The endpoint Mistral's embedding surface is one HTTP route on la Plateforme: `POST https://api.mistral.ai/v1/embeddings` Auth is a bearer token: `Authorization: Bearer $MISTRAL_API_KEY`, the same workspace key used for chat completions. Content type is `application/json`. ## The request body Two fields matter: - `model` — the embedding model id. The general-purpose one is `mistral-embed`. - `input` — an **array of strings**. Sending an array is the normal case, not an optimisation: one HTTP call can carry many texts, which matters enormously when you are embedding a corpus, because per-request overhead and rate-limit accounting are both per call. That is it. Unlike the chat endpoint there is no temperature, no streaming, no tools — embedding is deterministic given the model, so none of the sampling parameters exist here. ## The response body ``` { "id": "...", "object": "list", "model": "mistral-embed", "data": [ {"object": "embedding", "embedding": [0.018, -0.024, ...], "index": 0}, {"object": "embedding", "embedding": [...], "index": 1} ], "usage": {"prompt_tokens": 15, "total_tokens": 15} } ``` The key operational detail is `index`. There is no echo of your original text and no id you supplied — the only correspondence between input and output is positional, carried by `index`. So when you fan a batch out, keep your own parallel list (or a dict keyed by index) and rebuild the pairing on the way back. Code that assumes `data` is already aligned to the input list is *usually* right, but reading `index` explicitly is the contract-correct way. ## Dimensionality `mistral-embed` emits a fixed **1024-dimension** float vector. The request has no dimension knob for this model: you cannot ask for 256 or 512 dimensions and you cannot ask for a quantised output type. That is a fact worth knowing before you size storage or pick an index configuration — the vector width is a property of the model, not a request parameter. As of mid-2026 Mistral also ships a code-specialised embedding model, Codestral Embed, whose API does expose `output_dimension` and `output_dtype` so you can trade recall for footprint. If your interviewer asks "can I shrink Mistral vectors?", the accurate answer is "not with `mistral-embed`; that is a capability of the code embedding model, and otherwise you shrink them yourself downstream." ## Usage, billing and limits `usage.prompt_tokens` is the token count of everything you sent, and embeddings are billed per input token — there are no output tokens to pay for. There is a maximum sequence length per input string; an input beyond it is rejected with a 4xx error rather than truncated, so chunking is your responsibility before the call, not the API's. A single request also has a practical ceiling on how many strings and how many total tokens it will accept, which is why bulk pipelines send batches of a few dozen to a few hundred chunks rather than the whole corpus in one body. Rate limits on la Plateforme are workspace-level and expressed in both requests and tokens per minute; a `429` on the embeddings route is handled like any other — exponential backoff with jitter, and reduce batch size if it is the token limit you are hitting rather than the request limit. ## Practical shape of an ingestion loop 1. Chunk documents to sit inside the model's sequence limit. 2. Group chunks into batches sized to your token-per-minute allowance. 3. POST each batch; read `data[i].index` to re-attach vectors to chunk ids. 4. Retry `429`/`5xx` with backoff, and make retries idempotent by keying on your own chunk id. 5. If the corpus is large and not latency-sensitive, push the same requests through the asynchronous batch jobs API instead, which runs them offline at a discount. One consistency rule outlives the API detail: query vectors and document vectors must come from the same model. Mixing vectors produced by `mistral-embed` with vectors from any other model in one index produces silently meaningless similarity scores.