Quick Start

Get Endee running and make your first vector search in minutes.

Run Endee

Prerequisite: Install Docker Desktop for your OS (Mac, or Linux). That’s the only thing you need.

Once installed, verify it works:


docker --version

Then run Endee with a single command:


docker run \
  -p 8080:8080 \
  -v ./endee-data:/data \
  --name endee-server \
  endeeio/endee-server:latest

Docker pulls the image automatically if not already present, and Endee starts.

What each flag means:

Flag	Meaning
`-p 8080:8080`	Port mapping (your_machine:container). Makes the server reachable at localhost:8080
`-v ./endee-data:/data`	Stores Endee’s database files in an endee-data/ folder in your current directory
`--name endee-server`	Names the container so you can reference it easily (e.g. docker stop endee-server)
`e NDD_AUTH_TOKEN=your_token`	Optional. Protects the server with a token — every client request must include it. Omit to run with no authentication.
`endeeio/endee-server:latest`	The official pre-built Endee image from Docker Hub

Want to store data in a different folder? Replace ./endee-data with any path — only change the left side of the :, the right side (/data) is fixed:


-v ~/path/to/your/data/directory:/data     # stores in your home directory
-v C:/Users/YourName/endee-data:/data      # Windows local drive
-v /Volumes/MyDrive/endee-data:/data       # macOS external drive

Verify it’s running

Open http://localhost:8080 in your browser — you should see the Endee dashboard.

Stop the server


docker stop endee-server

Your data stays safe in the folder you configured.

Install the SDK

Python


pip install endee

Requirements: Python 3.8+

TypeScript


npm install endee
# or
yarn add endee

Requirements: Node.js 18+

Java


<!-- Maven (pom.xml) -->
<dependency>
  <groupId>io.endee</groupId>
  <artifactId>endee-java-client</artifactId>
  <version>1.0.1</version>
</dependency>

Requirements: Java 17+

Go


go get github.com/endee-io/endee-go-client

Requirements: Go 1.21+

Initialize the Client

The client connects to localhost:8080 by default.

Python


from endee import Endee
 
client = Endee()

TypeScript


import { Endee } from 'endee';
 
const client = new Endee();

Java


import io.endee.client.Endee;
 
Endee client = new Endee();

Go


import endee "github.com/endee-io/endee-go-client"
 
client := endee.EndeeClient("")

Using Authentication?

Python

Local server: If your server has NDD_AUTH_TOKEN set, pass the same token when initializing:


client = Endee("ndd-auth-token")
client.set_base_url("http://0.0.0.0:8080/api/v1")

See Authentication for details.

Endee Serverless: Go to app.endee.io , create a token, then pass it here:


client = Endee("your-serverless-token")

TypeScript

Local server: If your server has NDD_AUTH_TOKEN set, pass the same token when initializing:


const client = new Endee("ndd-auth-token");
client.setBaseUrl("http://0.0.0.0:8080/api/v1");

See Authentication for details.

Endee Serverless: Go to app.endee.io , create a token, then pass it here:


const client = new Endee("your-serverless-token");

Java

Local server: If your server has NDD_AUTH_TOKEN set, pass the same token when initializing:


Endee client = new Endee("ndd-auth-token");
client.setBaseUrl("http://0.0.0.0:8080/api/v1");

See Authentication for details.

Endee Serverless: Go to app.endee.io , create a token, then pass it here:


Endee client = new Endee("your-serverless-token");

Go

Local server: If your server has NDD_AUTH_TOKEN set, pass the same token when initializing:


client := endee.EndeeClient("ndd-auth-token")
client.BaseURL = "http://0.0.0.0:8080/api/v1"

See Authentication for details.

Endee Serverless: Go to app.endee.io , create a token, then pass it here:


client := endee.EndeeClient("your-serverless-token")

Create an Index

Python


from endee import Endee, Precision
 
client.create_index(
    name="my_index",
    dimension=384,
    space_type="cosine",
    precision=Precision.INT8
)

TypeScript


import { Endee, Precision } from 'endee';
 
await client.createIndex({
  name: 'my_index',
  dimension: 384,
  spaceType: 'cosine',
  precision: Precision.INT8,
});

Java


import io.endee.client.types.CreateIndexOptions;
import io.endee.client.types.Precision;
import io.endee.client.types.SpaceType;
 
client.createIndex(
    CreateIndexOptions.builder("my_index", 384)
        .spaceType(SpaceType.COSINE)
        .precision(Precision.INT8)
        .build()
);

Go


import endee "github.com/endee-io/endee-go-client"
 
err := client.CreateIndex(
  "my_index",             // name
  384,                    // dimension
  "cosine",               // space_type (cosine, l2, ip)
  16,                     // M - HNSW connectivity parameter 
  128,                    // ef_con - construction parameter
  endee.PrecisionInt8,    // precision (float32, float16, int16, int8, binary)
  nil,                    // version (optional)
)

Parameters:

Parameter	Description	Default
Name	Unique index name (alphanumeric + underscore, max 48 chars)	Required
Dimension	Dense vector dimensionality (max 10,000)	Required
Space Type	Distance metric: cosine, l2, or ip	Required
M	HNSW graph connectivity	16
EF Construction	HNSW construction parameter	128
Precision	Vector quantization level (see Precision)	INT8

Other index operations — list, get, describe, delete — are covered in Concepts → Indexes.

Upsert Vectors

Maximum 1,000 vectors per upsert call. Vector dimension must match the index dimension.

Python


index = client.get_index(name="my_index")
 
index.upsert([
    {
        "id": "doc1",
        "vector": [...],                        # 384-dim float list
        "meta": {"title": "First Document"},
        "filter": {"category": "tech"}
    },
    {
        "id": "doc2",
        "vector": [...],
        "meta": {"title": "Second Document"},
        "filter": {"category": "science"}
    }
])

TypeScript


const index = await client.getIndex('my_index');
 
await index.upsert([
  {
    id: 'doc1',
    vector: [...],                        // 384-dim float array
    meta: { title: 'First Document' },
    filter: { category: 'tech' },
  },
  {
    id: 'doc2',
    vector: [...],
    meta: { title: 'Second Document' },
    filter: { category: 'science' },
  },
]);

Java


import io.endee.client.Index;
import io.endee.client.types.VectorItem;
 
Index index = client.getIndex("my_index");
 
index.upsert(List.of(
    VectorItem.builder("doc1", new double[384])  
        .meta(Map.of("title", "First Document"))
        .filter(Map.of("category", "tech"))
        .build(),
    VectorItem.builder("doc2", new double[384])
        .meta(Map.of("title", "Second Document"))
        .filter(Map.of("category", "science"))
        .build()
));

Go


index, _ := client.GetIndex("my_index")
 
index.Upsert([]endee.VectorItem{
    {
        ID:     "doc1",
        Vector: []float32{ /* 384-dim float slice */ },
        Meta:   map[string]interface{}{"title": "First Document"},
        Filter: map[string]interface{}{"category": "tech"},
    },
    {
        ID:     "doc2",
        Vector: []float32{ /* 384-dim float slice */ },
        Meta:   map[string]interface{}{"title": "Second Document"},
        Filter: map[string]interface{}{"category": "science"},
    },
})

Vector fields:

Field	Required	Description
ID	Yes	Unique string identifier
Vector	Yes	Dense embedding array — must match index dimension
Meta	No	Arbitrary metadata returned in query results
Filter	No	Key-value pairs used for filtered queries

Search

Python


results = index.query(
    vector=[...],        # query embedding
    top_k=5,
    ef=128,
    include_vectors=False
)
 
for item in results:
    print(f"ID: {item['id']}, Similarity: {item['similarity']:.3f}")

TypeScript


const results = await index.query({
  vector: [...],
  topK: 5,
  ef: 128,
  includeVectors: false,
});
 
for (const item of results) {
  console.log(`ID: ${item.id}, Similarity: ${item.similarity.toFixed(3)}`);
}

Java


import io.endee.client.types.QueryOptions;
import io.endee.client.types.QueryResult;
 
List<QueryResult> results = index.query(
    QueryOptions.builder()
        .vector(new double[384]) 
        .topK(5)
        .ef(128)
        .includeVectors(false)
        .build()
);
 
for (QueryResult item : results) {
    System.out.printf("ID: %s, Similarity: %.3f%n",
        item.getId(), item.getSimilarity());
}

Go


results, _ := index.Query(
    []float32{ /* query embedding */ },
    nil, nil,
    5,
    nil,
    128,
    false,
    nil,
    0.5, 60,
)
 
for _, item := range results {
    fmt.Printf("ID: %s, Similarity: %.3f\n", item.ID, item.Similarity)
}

Query parameters:

Parameter	Description	Default	Max
Vector	Query embedding — must match index dimension	Required	—
Top K	Number of results to return	10	512
EF	Search quality — higher explores more candidates	128	1024
Include Vectors	Include stored vector data in results	false	—
Filter	Filter conditions	None	—

Filtered Query

Python


results = index.query(
    vector=[...],
    top_k=5,
    filter=[
        {"category": {"$eq": "tech"}},
        {"score": {"$range": [80, 100]}}
    ]
)

TypeScript


const results = await index.query({
  vector: [...],
  topK: 5,
  filter: [
    { category: { $eq: 'tech' } },
    { score: { $range: [80, 100] } },
  ],
});

Java


List<QueryResult> results = index.query(
    QueryOptions.builder()
        .vector(new double[384])  // replace with your query embedding
        .topK(5)
        .filter(List.of(
            Map.of("category", Map.of("$eq", "tech")),
            Map.of("score", Map.of("$range", List.of(80, 100)))
        ))
        .build()
);

Go


filter := map[string]interface{}{
    "category": map[string]interface{}{"$eq": "tech"},
    "score":    map[string]interface{}{"$range": []int{80, 100}},
}
 
results, _ := index.Query(
    []float32{ /* query embedding */ },
    nil, nil,
    5,
    filter,
    128,
    false,
    nil,
    0.5, 60,
)

Filter operators:

Operator	Description	Example
$eq	Exact match	{“status”: {“$eq”: “published”}}
$in	Match any value in list	{“tags”: {“$in”: [“ai”, “ml”]}}
$range	Numeric range (inclusive, values 0–999)	{“score”: {“$range”: [70, 95]}}

Next Steps

Concepts → Indexes — index types, parameters, distance metrics
Concepts → Vectors — vector fields, precision levels
Concepts → Search — search modes, hybrid queries, result fields
Concepts → Filtering — filter operators and tuning
Endee Tools → Sparse Vectors (BM25) — hybrid search with keyword matching