Skip to content

client.vectors

client.vectors is your app’s vector search: collections of entries you search by meaning. In text mode Muhkoo makes the vectors from your text; in vectors mode you send your own. See the Vector search guide for the concepts, limits and pricing.

Data calls are authorized by the app key; the app and environment come from the key, so test and live keys reach separate entries. A collection with backend access refuses the browser-safe publishable key. The owner calls (create, drop, notices) use your signed-in developer session and are owner-only.

The SDK does no validation of its own: server errors ({ error, code }) reach you as HttpError.

collection(name: string): VectorCollection

Returns a handle on the named collection. Cheap to make; it holds no state beyond its name.

const docs = client.vectors.collection("docs");
upsert(entries: VectorEntryInput[], opts?: VectorUpsertOptions): Promise<VectorWriteResult>

Adds or replaces entries (1 to 1,000 per call; an existing id is replaced in full). Returns once the write is accepted; entries usually become searchable within a minute or two. Needs vectors:write.

interface VectorEntryInput {
id: string; // 1-64 bytes, unique within the call
text?: string; // text mode: required, up to 8,192 bytes
vector?: number[]; // vectors mode: required, exactly `dimensions` numbers
data?: Record<string, unknown>; // declared fields are filterable; others are stored only
storeText?: boolean; // keep the text so query/get can return it (default false)
}
interface VectorUpsertOptions {
notify?: VectorNotify;
}
type VectorNotify = false | { space?: string; audience?: VectorAudience };
type VectorAudience = "everyone" | "writer";
interface VectorWriteResult {
mutationId: string;
count: number;
}

notify omitted sends a ready notice to the environment’s default notice Space, if it has one; false sends none; { space } must name a registered notice Space. See Ready notices.

query(input: VectorQueryInput): Promise<VectorMatch[]>

Returns the nearest entries to a text (text mode) or a vector (vectors mode). Needs vectors:read.

interface VectorQueryInput {
text?: string;
vector?: number[];
topK?: number; // default 10; max 50 with data or text, 100 without
filter?: Record<string, unknown>; // declared fields; $eq $ne $in $nin $lt $lte $gt $gte
includeData?: boolean; // default true
includeText?: boolean; // default false; text only if it was stored
}
interface VectorMatch {
id: string;
score: number;
data?: Record<string, unknown>;
text?: string;
}

String filters compare only a value’s first 64 bytes.

get(ids: string[], opts?: { includeVector?: boolean }): Promise<VectorEntry[]>

Entries by id (1 to 100). Ids that aren’t found are left out, and so are writes still pending. Needs vectors:read.

interface VectorEntry {
id: string;
data: Record<string, unknown>;
text?: string; // only if stored
vector?: number[]; // only with includeVector
}
delete(ids: string[]): Promise<VectorWriteResult>

Removes entries by id (1 to 1,000). Asynchronous, like upsert, and sends no notice. Needs vectors:write.

status(mutationId: string): Promise<VectorWriteState>
type VectorWriteState = "pending" | "done" | "unknown";

The state of a write. unknown means never seen or expired (pending for over 60 minutes). done is kept for at least 24 hours; don’t rely on unknown after that. Needs vectors:read.

waitFor(mutationId: string, opts?: { space?: Space; timeoutMs?: number }): Promise<void>

Resolves once the write is searchable: on its ready notice (with space) or when status answers done. It polls status either way, because notices are best effort. The notice only arrives if space is a registered notice Space for the environment, named in the write’s notify.space or set as the default; otherwise the wait completes by polling.

Rejects with an Error (“Unknown mutation …”) if status answers unknown, and with VectorWaitTimeoutError after timeoutMs (default 300,000 ms, 5 minutes).

upsertAndWait(
entries: VectorEntryInput[],
opts?: VectorUpsertOptions & { space?: Space; timeoutMs?: number },
): Promise<VectorWriteResult>

upsert, then waitFor its mutation. With space it listens before sending, so a notice that beats the HTTP response still counts. An upsert error is rethrown at once.

onReady(space: Space, handler: (e: VectorReadyEvent) => void): () => void
interface VectorReadyEvent {
collection: string;
ids: string[];
mutationId: string;
}

Listens on an open Space for this collection’s ready notices. Only notices the platform sent reach handler; a member publishing the same subject is ignored. Needs an unlocked session. Returns the unsubscribe.

These calls use the developer session and are owner-only, like the database tables API.

listCollections(appId: string): Promise<VectorCollectionInfo[]>

The app’s collections, sorted by name.

getCollection(appId: string, name: string): Promise<VectorCollectionInfo>

One collection. A missing or badly named one is 404 collection_not_found.

createCollection(
appId: string,
name: string,
definition: VectorCollectionDefinition,
): Promise<VectorCollectionInfo>

Creates a collection in both environments. Asynchronous: it answers with status creating; use waitForCollection. Repeating it with the same definition returns the existing collection; a different definition is 409 collection_exists. Definitions never change: drop and recreate.

type VectorCollectionDefinition =
| {
mode: "text";
model?: string; // default "bge-base-en-v1.5"
metric?: "cosine" | "euclidean" | "dot-product";
fields?: VectorFieldDefinition[];
access?: "app" | "backend";
}
| {
mode: "vectors";
dimensions: number; // 1-1536
metric?: "cosine" | "euclidean" | "dot-product";
fields?: VectorFieldDefinition[];
access?: "app" | "backend";
};
interface VectorFieldDefinition {
name: string;
type: "string" | "number" | "boolean";
}

Models: bge-small-en-v1.5 (384), bge-base-en-v1.5 (768, default), bge-large-en-v1.5 (1024), bge-m3 (1024, multilingual), qwen3-embedding-0.6b (1024, multilingual).

waitForCollection(appId: string, name: string, opts?: { timeoutMs?: number }): Promise<VectorCollectionInfo>

Polls getCollection every 2 s until status is ready. Rejects with VectorCollectionFailedError on failed, and with Error("Timed out waiting for collection <name>") after timeoutMs (default 600,000 ms, 10 minutes).

dropCollection(appId: string, name: string): Promise<void>

Drops a collection and its entries in both environments. Asynchronous; the collection shows status dropping until it is gone. Safe to repeat: a 503 vectors_unavailable means the drop couldn’t start, and calling again is the remedy.

setNotices(
appId: string,
name: string,
env: "live" | "test",
notices: VectorNotices,
): Promise<VectorNotices & { env: "live" | "test" }>
interface VectorNotices {
spaces: string[]; // up to 10 Space ids of this app and environment
defaultSpace: string | null; // null or one of `spaces`
}

Sets which Spaces receive ready notices for one environment.

interface VectorCollectionInfo {
name: string;
mode: "text" | "vectors";
model: string | null; // null in vectors mode
dimensions: number;
metric: string;
fields: VectorFieldDefinition[];
access: "app" | "backend";
createdAt: number;
status: "creating" | "ready" | "failed" | "dropping";
envs: { live: VectorEnvInfo; test: VectorEnvInfo };
}
interface VectorEnvInfo {
status: "creating" | "ready" | "failed" | "dropping";
entries: number | null; // last count read; null before the first
notices: VectorNotices;
error: string | null; // why, when status is "failed"
}

Thrown by waitFor and upsertAndWait when the wait runs out. The write itself was accepted; check status(err.mutationId) later.

import { VectorWaitTimeoutError } from "@muhkoo/connect";
try {
await docs.upsertAndWait(entries);
} catch (err) {
if (err instanceof VectorWaitTimeoutError) later(err.mutationId);
else throw err;
}

Thrown by waitForCollection when creation failed. err.info is the VectorCollectionInfo; info.envs.live.error or info.envs.test.error says why.

Server errors arrive as HttpError, with the body’s code. The 402s with owner_payment_past_due or user_plan_required arrive as its subclass PaymentRequiredError.

StatuscodeWhen
400invalid_collectionBad collection name on a data call
400invalid_entriesBad entries, or bad ids on get / delete
400entry_too_largeStored text plus data over 10,240 bytes
400invalid_queryBad query or filter
400invalid_mutationstatus without a mutation id
400notice_space_not_registerednotify.space isn’t a notice Space for the environment
400no_notice_spacenotify without space, and no default notice Space
400writer_needs_sessionaudience: "writer" without a publishable-key call and a signed-in user
400invalid_definitionBad definition or collection name on create
400invalid_notices, notice_space_invalidBad notices, or a Space not of this app and environment
402(none; requiresPaidTier)The app owner is on the Free plan
402vector_quotaOver quota
402owner_payment_past_dueThe owner’s payment is past due; upserts are refused, queries still work
402user_plan_requiredThe app takes paid Muhkoo accounts only
403backend_onlyA publishable key on a backend collection
403forbiddenThe key’s app or environment doesn’t match the collection
403The credential lacks vectors:read / vectors:write
404collection_not_foundNo such collection, or it is being dropped
409collection_not_readyThe collection is creating or failed (body has status)
409collection_existsCreate with a different definition
409collection_droppingCreate while a drop runs
409collection_limit20 collections already
429vector_rate_limitedOver 10 creates and drops per app per hour (Retry-After)
502vector_backend_errorThe search backend failed
502embedding_failedTurning text into a vector failed
503vector_backend_busyThe collection is being updated; retry after Retry-After
503vectors_unavailableCreate or drop couldn’t run; a repeated drop is safe