Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/No-Country-simulation/G9-LATAM-Team-58/llms.txt

Use this file to discover all available pages before exploring further.

The /embed endpoint generates a single 384-dimensional L2-normalized embedding vector for a given text string using the intfloat/multilingual-e5-small sentence transformer. It is called internally by the Spring API for two distinct purposes: encoding search queries (for GET /search) and encoding documents at ingestion time (for POST /content). The type parameter controls which E5 asymmetric prefix is applied before encoding — getting this right is critical for retrieval quality. This is an inference service endpoint — it runs on FastAPI (port 8000) and is not exposed to the public internet. This documentation is for developers running, testing, or integrating the inference service directly.

​
Endpoint

POST /embed
Base URL: http://inference:8000 (internal Docker network); http://localhost:8000 when running locally
Auth: None
Content-Type: application/json

​
Request Body

​
text
string
required
The text to encode into an embedding vector. May be a search query or a document body depending on the intended use.
​
type
string
required
Encoding mode. Must be exactly "query" or "passage" (Pydantic Literal validation). Any other value returns a 422 Unprocessable Entity error. See the table below for which value to use in each context.

​
The query vs passage distinction

The intfloat/multilingual-e5-small model uses asymmetric prefixes to differentiate query embeddings from document embeddings. Passing the wrong type silently produces an embedding in the wrong subspace, degrading cosine similarity scores without any error.
typeE5 prefix appliedFormatted inputUsed for
"query""query: ""query: {text}"Search queries (GET /search)
"passage""passage: ""passage: {text}"Document indexing (POST /content)
Using type=passage for a search query, or type=query when indexing a document, degrades retrieval quality silently — the API returns 200 with a valid embedding, but the vector sits in the wrong part of the embedding space. Always match type to the intended use case.

​
Response — 200 OK

​
embedding
float[]
required
A 384-dimensional L2-normalized float32 vector. Each element is a floating-point number in the range approximately [-1, 1]. The full vector is 1536 bytes when stored as float32. When persisted in Oracle via the Spring API, this vector is converted using VectorUtils.toBytes().

​
Example

​
Request

curl -X POST http://localhost:8000/embed \
  -H 'Content-Type: application/json' \
  -d '{"text":"apis rest en java","type":"query"}'

​
Response

{
  "embedding": [0.021, -0.118, 0.043, "...", 0.0]
}

​
Error Codes

HTTP StatusDescription
422type is not "query" or "passage". Pydantic rejects the value at deserialization time before any model inference occurs.
503Model not loaded — the inference service is still initializing or the artifact failed to load.

​
422 error response

{
  "detail": [
    {
      "type": "literal_error",
      "loc": ["body", "type"],
      "msg": "Input should be 'query' or 'passage'",
      "input": "document",
      "ctx": { "expected": "'query' or 'passage'" }
    }
  ]
}

​
Implementation notes

The embedding returned by /embed is 384 floats (1536 bytes as float32). When stored in Oracle through the Spring API, it is serialized using VectorUtils.toBytes() and written to an Oracle VECTOR column. The same conversion is applied to query embeddings at search time before VECTOR_DISTANCE is computed.

Build docs developers (and LLMs) love

Get started for freeTalk to us