Skip to content

Embeddings

The embeddings endpoint generates vector representations of text, called embeddings. You can use them for semantic search, clustering, classification and retrieval-augmented generation (RAG) pipelines.

Endpoint

POST /v1/embeddings

The endpoint requires the embeddings scope. See Authentication.

Request Body

Field Type Required Description
model string Recommended The embedding model's ID or name. Get them from Listing Models. If you leave it out, the first available embedding model is used — which may change as Nodes come and go, so always set it for anything you store
input string or array Yes The text to embed. Can be a single string or an array of strings for batch embedding.
encoding_format string No The format for the returned vectors. "float" (default) returns an array of floating-point numbers.

Example — Single Input

Request:

{
  "model": "nomic-embed-text",
  "input": "The quick brown fox jumps over the lazy dog"
}

Response:

{
  "object": "list",
  "model": "nomic-embed-text",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0094, 0.0156, ...]
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "total_tokens": 10
  }
}

The embedding array contains the vector. Its length (dimensionality) depends on the model — you can check the dimensions field in the model listing.

Example — Batch Input

You can pass an array of strings to embed several texts in a single request:

Request:

{
  "model": "nomic-embed-text",
  "input": [
    "Paris is the capital of France.",
    "Berlin is the capital of Germany.",
    "Tokyo is the capital of Japan."
  ]
}

Response:

{
  "object": "list",
  "model": "nomic-embed-text",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [...] },
    { "object": "embedding", "index": 1, "embedding": [...] },
    { "object": "embedding", "index": 2, "embedding": [...] }
  ],
  "usage": {
    "prompt_tokens": 27,
    "total_tokens": 27
  }
}

Results will be returned in the same order as the input array.

Finding Available Embedding Models

Use the /onveris/v1/models endpoint to list available models. Embedding models appear in the embed_models array. Each entry includes the model ID and the vector dimensions. See Listing Models.

Every Node includes OnVeris Built-in Embeddings, a small embedding model that runs on the CPU, if your administrator has started it.

Notes

Keep the following in mind when you work with embeddings:

  • Embedding models are separate from language models. You cannot use a chat model ID with this endpoint, or an embedding model ID with /v1/chat/completions.
  • The same vector dimensions must be used consistently throughout a project. Embeddings from different models (or even the same model at different quantisations) are not compatible with each other.
  • For RAG pipelines, embed both your document corpus and your query with the same model, then compare using cosine similarity or dot product.