API Documentation

Click any endpoint below to see details, examples, and copy-paste code.

Need an API key? Create one here (requires sign in).

What is this?

An API that lets you do two things — use either one or both together:

1. Turn text into numbers

Give it any text, get back a list of numbers (called an "embedding") that captures the meaning of that text. Two similar sentences will produce similar numbers.

Use case: compare text similarity, build recommendations, power AI features.

2. Store & search by meaning

Save your documents, and later search them by meaning instead of exact keywords. Ask "how to deploy?" and find a doc about "shipping to production".

Use case: AI chatbot knowledge base, semantic search, document Q&A.

How the Vector Database is structured

📁 Project — top-level container (e.g. "my-saas-app")

📊 Collection — a vector database (e.g. "user-docs")

📄 Document — "React is a JavaScript library..." category: frontend

📄 Document — "Docker makes deployment easy..." category: devops

...more documents

📊 Collection — another vector database (e.g. "chat-logs")

📊 Collection — another vector database (e.g. "help-articles")

📁 Another Project — completely separate (e.g. "chatbot")

You can have unlimited projects, each with multiple collections, each with millions of documents.

Getting Started

Get your API key

Go to API Keys and create a new key. Copy it — you’ll need it for every request.

Set your base URL and headers

Every request goes to the same base URL with your API key in the header:

const API = "https://embeddings.anantgupta.xyz";
const headers = {
  "x-api-key": "YOUR_KEY",
  "Content-Type": "application/json"
};

import requests

API = "https://embeddings.anantgupta.xyz"
headers = {"x-api-key": "YOUR_KEY"}

# Base URL
https://embeddings.anantgupta.xyz

# Required header on every request
-H "x-api-key: YOUR_KEY"

Make your first call

See the examples under each endpoint below, or try one of these:

Generate an embedding Store & search documents

Note: In the endpoints below, :project and :collection are placeholders. Replace them with your actual names, e.g. /projects/myapp/collections/docs/search

Embedding Endpoints

Turn text into numbers. No storage, no setup — just send text and get embeddings back.

const res = await fetch(API + "/embed", {
  method: "POST", headers,
  body: JSON.stringify({ texts: ["hello world", "another text"] })
});
const { vectors } = await res.json();
// vectors[0] = [0.012, -0.034, ...] (1024 numbers per text)

res = requests.post(f"{API}/embed",
    headers=headers, json={"texts": ["hello world", "another text"]})
vectors = res.json()["vectors"]
# vectors[0] = [0.012, -0.034, ...] (1024 numbers per text)

POST/embed

Convert one or more texts into embedding vectors

Example path:POST /embed

Request Body

textsstring[]Array of texts to embed

{"texts": ["hello world", "another text"]}

Response 200 OK

vectorsnumber[][]Array of embedding vectors (1024 numbers each)

dimensionsnumberVector size (1024)

countnumberNumber of texts embedded

{"vectors": [[0.012, -0.034, ...]], "dimensions": 1024, "count": 2}

curl -X POST https://embeddings.anantgupta.xyz/embed -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"texts": ["hello world", "another text"]}'

OpenAI-Compatible Endpoint Drop-in replacement

Already using OpenAI embeddings? Just change the base URL — no code changes needed. Works with the official OpenAI SDKs.

Endpoint: POST /v1/embeddings

Auth: Authorization: Bearer YOUR_KEY

Model: bge-m3

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_KEY",
    base_url="https://embeddings.anantgupta.xyz/v1"
)

# Single text
response = client.embeddings.create(
    input="hello world",
    model="bge-m3"
)
vector = response.data[0].embedding  # 1024 numbers

# Multiple texts
response = client.embeddings.create(
    input=["hello", "world"],
    model="bge-m3"
)
vectors = [d.embedding for d in response.data]

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: "YOUR_KEY",
    baseURL: "https://embeddings.anantgupta.xyz/v1"
});

const response = await client.embeddings.create({
    input: "hello world",
    model: "bge-m3"
});
const vector = response.data[0].embedding; // 1024 numbers

curl -X POST https://embeddings.anantgupta.xyz/v1/embeddings \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "hello world", "model": "bge-m3"}'

Migrating from OpenAI?

Just change two things:

base_url = "https://api.openai.com/v1" → base_url = "https://embeddings.anantgupta.xyz/v1"

api_key = "sk-..." → api_key = "emb_..."

Note: Dimensions change from 1536 (OpenAI) to 1024 (BGE-M3). If your vector DB has a fixed dimension, you’ll need to recreate the index.

Storage — Projects

A project is like a folder. It groups your collections together.

GET/projects

List all your projects and their collections

Example path:GET /projects

No request body needed.

Response 200 OK

projectsobjectMap of project names to their collection names

{"projects": {"myapp": ["docs", "code"]}}

curl -X GET https://embeddings.anantgupta.xyz/projects -H "x-api-key: YOUR_KEY"

DELETE/projects/:project

Delete a project and all its collections permanently

Example path:DELETE /projects/myapp

No request body needed.

Response 200 OK

deletednumberNumber of collections removed

collectionsstring[]Names of deleted collections

{"deleted": 2, "collections": ["myapp__docs", "myapp__code"]}

curl -X DELETE https://embeddings.anantgupta.xyz/projects/myapp -H "x-api-key: YOUR_KEY"

Storage — Collections

A collection is a searchable database inside a project. Think of it like a table that understands meaning.

POST/projects/:project/collections

Create a new collection in a project

Example path:POST /projects/myapp/collections

Request Body

namestringCollection name (e.g. "docs")

distancestring?Optional. Default: "Cosine"

{"name": "docs"}

Response 200 OK

createdstringFull collection ID

vectorSizenumberEmbedding dimensions (1024)

{"created": "myapp__docs", "vectorSize": 1024}

curl -X POST https://embeddings.anantgupta.xyz/projects/myapp/collections -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"name": "docs"}'

GET/projects/:project/collections

List all collections in a project

Example path:GET /projects/myapp/collections

No request body needed.

Response 200 OK

projectstringProject name

collectionsstring[]List of collection names

{"project": "myapp", "collections": ["docs", "code"]}

curl -X GET https://embeddings.anantgupta.xyz/projects/myapp/collections -H "x-api-key: YOUR_KEY"

GET/projects/:project/collections/:collection

Get collection details (vector count, config)

Example path:GET /projects/myapp/collections/docs

No request body needed.

Response 200 OK

infoobjectCollection stats including points_count, config, etc.

{"project": "myapp", "collection": "docs", "info": {"points_count": 450}}

curl -X GET https://embeddings.anantgupta.xyz/projects/myapp/collections/docs -H "x-api-key: YOUR_KEY"

DELETE/projects/:project/collections/:collection

Delete a collection and all its stored vectors

Example path:DELETE /projects/myapp/collections/docs

No request body needed.

Response 200 OK

deletedstringName of the deleted collection

{"deleted": "myapp__docs"}

curl -X DELETE https://embeddings.anantgupta.xyz/projects/myapp/collections/docs -H "x-api-key: YOUR_KEY"

Storage — Documents

Add text to a collection. The text is automatically converted to an embedding and stored — you just send the text.

// Add documents
await fetch(API + "/projects/myapp/collections/docs/documents", {
  method: "POST", headers,
  body: JSON.stringify({ documents: [
    { id: 1, text: "React is great for UIs", metadata: { category: "frontend" } },
    { id: 2, text: "Express handles routing", metadata: { category: "backend" } }
  ]})
});

# Add documents
requests.post(f"{API}/projects/myapp/collections/docs/documents",
    headers=headers, json={"documents": [
        {"id": 1, "text": "React is great for UIs", "metadata": {"category": "frontend"}},
        {"id": 2, "text": "Express handles routing", "metadata": {"category": "backend"}}
    ]})

POST/projects/:project/collections/:collection/documents

Add documents — text is auto-embedded and stored

Example path:POST /projects/myapp/collections/docs/documents

Request Body

documentsarrayArray of documents to store

documents[].idnumberUnique ID for this document

documents[].textstringThe text content to embed and store

documents[].metadataobject?Optional key-value pairs for filtering

{"documents": [{"id": 1, "text": "React is a JS library", "metadata": {"category": "frontend"}}]}

Response 200 OK

storednumberNumber of documents stored

{"stored": 1, "collection": "myapp__docs"}

curl -X POST https://embeddings.anantgupta.xyz/projects/myapp/collections/docs/documents -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"documents": [{"id": 1, "text": "React is a JS library", "metadata": {"category": "frontend"}}]}'

GET/projects/:project/collections/:collection/documents

Browse stored documents (paginated). Use ?limit=10&offset=...

Example path:GET /projects/myapp/collections/docs/documents

No request body needed.

Response 200 OK

documentsarrayArray of stored documents with text and metadata

next_offsetstring?Pass this as ?offset= to get the next page

{"documents": [{"id": 1, "text": "...", "category": "frontend"}], "next_offset": "..."}

curl -X GET https://embeddings.anantgupta.xyz/projects/myapp/collections/docs/documents -H "x-api-key: YOUR_KEY"

DELETE/projects/:project/collections/:collection/documents

Delete specific documents by their IDs

Example path:DELETE /projects/myapp/collections/docs/documents

Request Body

idsnumber[]Array of document IDs to delete

{"ids": [1, 2, 3]}

Response 200 OK

deletednumberNumber of documents removed

{"deleted": 3}

curl -X DELETE https://embeddings.anantgupta.xyz/projects/myapp/collections/docs/documents -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"ids": [1, 2, 3]}'

Storage — Search

Find documents by meaning. Ask "how to deploy?" and it’ll find your doc about "shipping to production" — even though the words are different.

const res = await fetch(API + "/projects/myapp/collections/docs/search", {
  method: "POST", headers,
  body: JSON.stringify({ query: "frontend development", limit: 5 })
});
const { results } = await res.json();
// results[0] = { id: 1, score: 0.89, text: "React is great for UIs" }

res = requests.post(f"{API}/projects/myapp/collections/docs/search",
    headers=headers, json={"query": "frontend development", "limit": 5})
results = res.json()["results"]
# results[0] = {"id": 1, "score": 0.89, "text": "React is great for UIs"}

POST/projects/:project/collections/:collection/search

Semantic search — find documents by meaning

Example path:POST /projects/myapp/collections/docs/search

Request Body

querystringYour search text (searched by meaning, not keywords)

limitnumber?Max results to return (default: 5)

filterobject?Optional metadata filter (see Filtering below)

{"query": "frontend frameworks", "limit": 5}

Response 200 OK

resultsarrayMatched documents, sorted by relevance

results[].idnumberDocument ID

results[].scorenumberSimilarity score (0 to 1, higher = better match)

results[].textstringThe document text

results[].*anyAny metadata fields from the document

{"results": [{"id": 1, "score": 0.95, "text": "React is a JS library", "category": "frontend"}]}

curl -X POST https://embeddings.anantgupta.xyz/projects/myapp/collections/docs/search -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" -d '{"query": "frontend frameworks", "limit": 5}'

Filtering search results

If your documents have metadata (like category), you can filter search to only match specific values:

// "Find deployment docs, but only in the devops category"
{
  "query": "deployment",
  "limit": 5,
  "filter": {
    "must": [{ "key": "category", "match": { "value": "devops" } }]
  }
}

Metadata is set when you add documents: {"id": 1, "text": "...", "metadata": {"category": "devops"}}

Errors & Limits

Authentication: Every request needs an x-api-key header. Missing or invalid key returns 401.

Errors: Failed requests return {"error": "description"} with appropriate HTTP status (400, 404, 500).

Batch size: Embed up to 32 texts per request. For documents, send up to 8 at a time (each gets embedded on the server).

Text length: Up to 8,192 tokens per text (~6,000 words).

Names: Project and collection names must be 1-64 characters, alphanumeric with hyphens and underscores.

Use cases

AI Chatbot

Store your docs, let users ask questions in natural language

Semantic Search

Search blog posts, help articles, or products by meaning

Recommendations

Find similar items — articles, products, or content

RAG / AI Apps

Retrieve relevant context to feed into LLMs like GPT or Claude