API Reference

// POST /v1/tenants
// dim and metric are optional and default to the server's -dim and -metric
{ "tenant_id": "acme", "dim": 2, "metric": "cosine", "max_vectors": 1000 }
// response
{}

// PUT /v1/tenants/acme/quota
{ "max_vectors": 5000, "max_qps": 50 }
// response
{}

// GET /v1/tenants  (metric is the DistanceMetric enum number)
{"tenants":[{"tenant_id":"acme","quota":{"max_vectors":5000,"max_qps":50},"dim":2,"metric":1},
            {"tenant_id":"default","vector_count":2,"quota":{},"dim":4,"metric":2}]}

// DELETE /v1/tenants/acme  (removes its files; "default" can't be deleted)
{}

// POST /v1/vectors
{ "id": "1", "values": [1, 0, 0, 0], "metadata": {"team": "search"} }
// response
{ "id": "1" }

// POST /v1/vectors:batch  (one shared WAL fsync per tenant in the batch)
{ "vectors": [
  { "id": "1", "values": [1, 0, 0, 0], "metadata": {"team": "search", "year": "2023"} },
  { "id": "2", "values": [0, 1, 0, 0], "metadata": {"team": "ads", "year": "2025"} }
] }
// response
{"upserted":2}

// PATCH /v1/vectors/2  (replaces all metadata, keeps the vector)
{ "metadata": {"team": "infra", "year": "2025"} }
// response
{}

// DELETE /v1/vectors/{id}?tenant_id=acme
{ "deleted": true }

// GET /v1/vectors/2
{"vector":{"id":"2","values":[0,1,0,0],"metadata":{"team":"ads","year":"2025"}}}

// GET /v1/vectors?page_size=1  (pass next_page_token back as page_token)
{"ids":["1"],"next_page_token":"2"}

// GET /v1/vectors:count
{"count":2}

// POST /v1/search
{
  "query": [1, 0, 0, 0],
  "top_k": 5,              // capped at 1000
  "ef_search": 0,          // 0 = server default (64), capped at 10000
  "filters": {"team": "infra"},          // key=value matches
  "where": [{"key": "year", "op": "gte", "value": "2024"}]
}
// response
{"matches":[{"id":"2","score":2,"metadata":{"team":"infra","year":"2025"}}]}

[{"key": "at-least-16-characters", "tenants": ["acme"]},
 {"key": "an-admin-key-for-ops", "tenants": ["*"], "admin": true}]

rpc CreateTenant(CreateTenantRequest) returns (CreateTenantResponse);
rpc Insert(InsertRequest) returns (InsertResponse);
rpc BatchUpsert(BatchUpsertRequest) returns (BatchUpsertResponse);
rpc Delete(DeleteRequest) returns (DeleteResponse);
rpc Search(SearchRequest) returns (SearchResponse);
rpc Get(GetRequest) returns (GetResponse);
rpc List(ListRequest) returns (ListResponse);
rpc Count(CountRequest) returns (CountResponse);
rpc UpdateMetadata(UpdateMetadataRequest) returns (UpdateMetadataResponse);
rpc DeleteTenant(DeleteTenantRequest) returns (DeleteTenantResponse);
rpc SetQuota(SetQuotaRequest) returns (SetQuotaResponse);
rpc ListTenants(ListTenantsRequest) returns (ListTenantsResponse);

message CreateTenantRequest {
  string tenant_id = 1;
  TenantQuota quota = 2;
  int32 dim = 3;            // 0 = server default
  DistanceMetric metric = 4; // UNSPECIFIED = server default
}

message TenantQuota {
  int64 max_vectors = 1;  // 0 means unlimited
  double max_qps = 2;     // 0 means unlimited
}

message Vector {
  string id = 1;
  repeated float values = 2;
  map<string, string> metadata = 3;
  string tenant_id = 4;
}

message SearchRequest {
  repeated float query = 1;
  int32 top_k = 2;
  DistanceMetric metric = 3; // must match the tenant's metric if set
  int32 ef_search = 4;
  repeated MetadataFilter filters = 5;
  string tenant_id = 6;
}

message MetadataFilter {
  string key = 1;
  string value = 2;           // for EQ, NE and the numeric ops
  FilterOp op = 3;
  repeated string values = 4; // for IN and NOT_IN
}

enum FilterOp {
  FILTER_OP_EQ = 0; FILTER_OP_NE = 1; FILTER_OP_IN = 2; FILTER_OP_NOT_IN = 3;
  FILTER_OP_GT = 4; FILTER_OP_GTE = 5; FILTER_OP_LT = 6; FILTER_OP_LTE = 7;
  FILTER_OP_EXISTS = 8;
}

enum DistanceMetric {
  DISTANCE_METRIC_UNSPECIFIED = 0;
  DISTANCE_METRIC_COSINE = 1;
  DISTANCE_METRIC_L2 = 2;
  DISTANCE_METRIC_DOT = 3;
}