API Reference

API Reference

All endpoints accept and return JSON. The base URL is http://localhost:8080 by default.

Health & Metrics

GET /healthz

Liveness check. Always returns 200 if the process is running.

Response 200 OK

{
  "status": "ok"
}

GET /readyz

Readiness check. Verifies S3 connectivity.

Response 200 OK

{
  "status": "ready",
  "s3_connected": true
}

Response 503 Service Unavailable

{
  "status": "not_ready",
  "s3_connected": false,
  "error": "connection refused"
}

GET /metrics

Prometheus-formatted metrics. See Metrics Reference for the full list.

Response 200 OK — text/plain; version=0.04; charset=utf-8

---

Namespaces

POST /v1/namespaces

Create a new namespace.

Request

{
  "name": "my_namespace",
  "dimensions": 384,
  "distance_metric": "cosine",
  "full_text_search": {
    "content": {
      "language": "english",
      "stemming": true,
      "remove_stopwords": true,
      "case_sensitive": false,
      "k1": 1.2,
      "b": 0.75,
      "max_token_length": 40
    }
  }
}

Field	Type	Required	Default	Description
name	string	yes	—	1-255 chars, starts with alphanumeric, [a-zA-Z0-9._-] only
dimensions	integer	yes	—	Vector dimensions (1 to max_dimensions)
distance_metric	string	no	"cosine"	"cosine", "euclidean", or "dot_product"
full_text_search	object	no	{}	Map of field name to FtsFieldConfig

Response 201 Created

{
  "name": "my_namespace",
  "dimensions": 384,
  "distance_metric": "cosine",
  "index_type": "ivf_flat",
  "vector_count": 0,
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z",
  "full_text_search": {}
}

GET /v1/namespaces

List all namespaces.

Response 200 OK

[
  {
    "name": "my_namespace",
    "dimensions": 384,
    "distance_metric": "cosine",
    "index_type": "ivf_flat",
    "vector_count": 1000,
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T12:00:00Z",
    "full_text_search": {}
  }
]

GET /v1/namespaces/:ns

Get a single namespace's metadata.

Response 200 OK — Same schema as list items above.

Response 404 Not Found — Namespace does not exist.

DELETE /v1/namespaces/:ns

Delete a namespace and all its data (vectors, WAL fragments, segments).

Response 204 No Content

Response 404 Not Found — Namespace does not exist.

---

Vectors

POST /v1/namespaces/:ns/vectors

Upsert (insert or update) vectors. If a vector ID already exists, it is overwritten.

Request

{
  "vectors": [
    {
      "id": "vec-1",
      "values": [0.1, 0.2, 0.3],
      "attributes": {
        "category": "product",
        "price": 99.99,
        "in_stock": true,
        "tags": ["electronics", "gadgets"]
      }
    }
  ]
}

Field	Type	Required	Description
vectors	array	yes	Non-empty list of vector entries
vectors[].id	string	yes	1 to max_vector_id_length chars
vectors[].values	float[]	yes	Length must equal namespace dimensions
vectors[].attributes	object	no	Key-value metadata for filtering

Attribute value types:

JSON Type	AttributeValue	Example
string	String	"hello"
integer	Integer	42
number	Float	3.14
boolean	Bool	true
string[]	StringList	["a", "b"]
integer[]	IntegerList	[1, 2, 3]
number[]	FloatList	[1.5, 2.5]

Response 200 OK

{
  "upserted": 1
}

Validation errors (400):

• vectors array cannot be empty
• batch size N exceeds maximum of M
• vector id length N exceeds maximum of M
• dimension mismatch: expected N, got M

DELETE /v1/namespaces/:ns/vectors

Delete vectors by ID.

Request

{
  "ids": ["vec-1", "vec-2"]
}

Response 200 OK

{
  "deleted": 2
}

---

Query

POST /v1/namespaces/:ns/query

Search by vector similarity or BM25 full-text ranking. Exactly one of vector or rank_by must be provided.

Vector search request

{
  "vector": [0.1, 0.2, 0.3],
  "top_k": 10,
  "nprobe": 20,
  "filter": {
    "op": "eq",
    "field": "category",
    "value": "product"
  },
  "consistency": "strong"
}

BM25 search request

{
  "rank_by": ["content", "BM25", "search query"],
  "top_k": 10,
  "filter": {
    "op": "eq",
    "field": "language",
    "value": "english"
  },
  "last_as_prefix": true,
  "consistency": "strong"
}

Field	Type	Required	Default	Description
vector	float[]	one of vector/rank_by	—	Query vector (length = namespace dimensions)
rank_by	array	one of vector/rank_by	—	RankBy expression
top_k	integer	no	10	Results to return (1 to max_top_k)
nprobe	integer	no	config default	Clusters to probe (IVF only)
filter	object	no	—	Filter expression
consistency	string	no	"strong"	"strong" or "eventual"
last_as_prefix	boolean	no	false	Treat last BM25 token as prefix match

Response 200 OK

{
  "results": [
    {
      "id": "vec-1",
      "score": 0.95,
      "attributes": {
        "category": "product",
        "price": 99.99
      }
    }
  ],
  "scanned_fragments": 3,
  "scanned_segments": 1
}

Field	Description
results[].id	Vector ID
results[].score	Distance (vector, lower=better) or relevance (BM25, higher=better)
results[].attributes	Original attributes, or null
scanned_fragments	WAL fragments scanned (strong consistency)
scanned_segments	Index segments scanned

---

Error Format

All errors return:

{
  "error": "human-readable message",
  "status": 400
}

Status	Meaning
200	Success
201	Created
204	No Content (delete)
400	Validation error
404	Not found
409	Conflict (namespace exists, lease held, manifest conflict)
500	Internal server error
503	Service unavailable (S3 unreachable)