Embeddings & Semantic Search

POST /v1/text/embed turns a batch of strings into dense vectors. It runs on a GPU worker with the all-MiniLM-L6-v2 sentence-embedding model (384 dimensions), which is a good default for semantic search, clustering, near-duplicate detection, and RAG retrieval where you want cosine similarity over meaning rather than over words.

This is the semantic counterpart to the lexical tools in Similarity and Diff: similarity compares two strings with Levenshtein/cosine/Jaccard, embed gives you the vectors so you can compare any pair, thousands of them, or index a whole corpus.

Method Endpoint Purpose
POST /v1/text/embed Embed a batch of 1–100 texts

Base URL

https://textanalysis.toolkitapi.io

All requests need an X-API-Key header.

Request

The body is a bare JSON array of strings — not an object with a texts key.

Field Type Required Constraints
(body) string[] Yes 1–100 entries. Empty array → 422. More than 100 → 422.
curl -X POST "https://textanalysis.toolkitapi.io/v1/text/embed" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    "How do I rotate an API key?",
    "Where can I change my API credentials?",
    "The cat sat on the mat."
  ]'

Python

import requests

resp = requests.post(
    "https://textanalysis.toolkitapi.io/v1/text/embed",
    headers={"X-API-Key": API_KEY},
    json=[
        "How do I rotate an API key?",
        "Where can I change my API credentials?",
        "The cat sat on the mat.",
    ],
    timeout=120,  # GPU cold start can take a few seconds
)
data = resp.json()
print(data["model"], data["dimensions"], data["count"])
vectors = data["embeddings"]

JavaScript

const resp = await fetch("https://textanalysis.toolkitapi.io/v1/text/embed", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TOOLKIT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    "How do I rotate an API key?",
    "Where can I change my API credentials?",
    "The cat sat on the mat.",
  ]),
});
const { embeddings, dimensions, model } = await resp.json();

Response

Field Type Description
status string "ok" on success.
embeddings number[][] One vector per input string, in the same order.
dimensions integer | null Vector length (384 for all-MiniLM-L6-v2). Use this as the source of truth — don't hardcode 384.
model string Model identifier, defaults to all-MiniLM-L6-v2.
count integer Number of vectors returned (equals the number of inputs).
task_id string Internal GPU task id — useful when filing a support ticket.
{
  "status": "ok",
  "embeddings": [[0.021, -0.134, ...], [0.019, -0.129, ...], [-0.311, 0.502, ...]],
  "dimensions": 384,
  "model": "all-MiniLM-L6-v2",
  "count": 3,
  "task_id": "gpu-7f3c1a9e"
}

Recipes

Cosine similarity matrix (Python, no NumPy)

import math, requests

def cosine(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    na = math.sqrt(sum(x * x for x in a))
    nb = math.sqrt(sum(y * y for y in b))
    return dot / (na * nb) if na and nb else 0.0

texts = ["reset my password", "change my password", "pizza recipes"]
vecs = requests.post(
    "https://textanalysis.toolkitapi.io/v1/text/embed",
    headers={"X-API-Key": API_KEY},
    json=texts,
    timeout=120,
).json()["embeddings"]

print(round(cosine(vecs[0], vecs[1]), 3))  # ~0.8, strongly related
print(round(cosine(vecs[0], vecs[2]), 3))  # low, unrelated

Semantic search over a knowledge base

import math, requests

def embed(batch):
    r = requests.post(
        "https://textanalysis.toolkitapi.io/v1/text/embed",
        headers={"X-API-Key": API_KEY}, json=batch, timeout=120,
    )
    r.raise_for_status()
    return r.json()["embeddings"]

def cosine(a, b):
    return sum(x * y for x, y in zip(a, b)) / (
        math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)) or 1
    )

docs = load_docs()                       # ["doc one", "doc two", ...]
doc_vecs = []
for i in range(0, len(docs), 100):       # respect the 100-item cap
    doc_vecs += embed(docs[i:i + 100])

query_vec = embed(["how do I authenticate requests?"])[0]
ranked = sorted(zip(docs, doc_vecs), key=lambda d: cosine(query_vec, d[1]), reverse=True)
top = [doc for doc, _ in ranked[:5]]

Near-duplicate detection

Embed each item once, bucket pairs whose cosine ≥ 0.95, and keep one representative per bucket. Cheaper and far more accurate on paraphrases than the lexical methods.

Storing vectors

Embeddings are plain JSON floats. To store them in Postgres, cast on write: INSERT INTO docs(embedding) VALUES (%s::vector) with pgvector, or keep them in a float[] column. Because the model is fixed per call, always store model next to the vector and re-embed if it changes.

Errors

Status Condition
401 Missing / invalid API key.
422 Empty array, more than 100 texts, or a non-string element.
503 GPU task API is currently unavailable — retry with backoff.
504 Embedding generation timed out — retry, or split a very large batch.
500 GPU worker returned an error.

Notes & gotchas

  • Order is preserved. embeddings[i] corresponds to input texts[i]; there is no id echo, so keep your own index.
  • Batch up. One call with 100 texts is dramatically cheaper and faster than 100 calls. The cap is hard: 100 per request.
  • Cold starts. A GPU worker that has been idle may take several seconds on the first request. Use a generous client timeout (60–120 s) and don't interpret one slow call as an outage.
  • Truncation. Sentence-transformer models have a fixed context (typically 256–512 tokens for MiniLM). Very long documents get truncated — chunk to a few paragraphs before embedding rather than sending whole pages.
  • Normalise only if you want to. Cosine ignores magnitude; if you plan to use dot products instead, L2-normalise the vectors yourself once at write time.
  • Dimensions are model-dependent. Read dimensions from the response instead of assuming 384, and always pair an index with the model that produced it.

See also