MossClient
MossClient - Async-first semantic search client for vector similarity operations. All mutations (createIndex, addDocs, deleteDocs) are async operations that run server-side and poll until complete.Example
Constructors
Constructor
new MossClient(Creates a new MossClient instance.projectId,projectKey):MossClient
Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | Your project identifier. |
projectKey | string | Your project authentication key. Use the projectKey form for server-side code only. |
Returns
MossClient
Constructor (custom authenticator)
new MossClient(Creates a new MossClient instance with a custom authenticator. Use this pattern from browser or untrusted clients where theprojectId,authenticator):MossClient
projectKey must never be embedded in shipped code.
See the Custom Authenticator guide for details.
Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | Your project identifier. |
authenticator | IAuthenticator | Implementation that returns a short-lived bearer token from your backend. |
Methods
createIndex()
createIndex(Creates a new index with the provided documents via async upload. Handles the full flow: init, upload, build, then poll until complete. Returns when the index is ready. When all documents have pre-computed embeddings, they are serialized as raw float32 in the binary upload. When no documents have embeddings, the server generates embeddings in batches (dimension=0 flow). Mixed documents (some with embeddings, some without) are rejected.indexName,docs,options?):Promise<MutationResult>
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the index to create. |
docs | DocumentInfo[] | Documents, optionally with pre-computed embeddings. |
options? | CreateIndexOptions | Optional model ID and progress callback. |
Returns
Promise<MutationResult>
Promise that resolves to MutationResult when the index is ready.
Throws
If the index already exists or creation fails.Example
getIndex()
getIndex(Gets information about a specific index.indexName):Promise<IndexInfo>
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the index to retrieve. |
Returns
Promise<IndexInfo>
Promise that resolves to IndexInfo object.
Throws
If the index does not exist.Example
listIndexes()
listIndexes():Lists all available indexes.Promise<IndexInfo[]>
Returns
Promise<IndexInfo[]>
Promise that resolves to array of IndexInfo objects.
Example
deleteIndex()
deleteIndex(Deletes an index and all its data.indexName):Promise<boolean>
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the index to delete. |
Returns
Promise<boolean>
Promise that resolves to true if successful.
Throws
If the index does not exist.Example
addDocs()
addDocs(Adds or updates documents in an index asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.indexName,docs,options?):Promise<MutationResult>
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the target index. |
docs | DocumentInfo[] | Documents to add or update. |
options? | MutationOptions | Optional configuration (upsert, onProgress callback). |
Returns
Promise<MutationResult>
Promise that resolves to MutationResult when the operation is complete.
Throws
If the index does not exist.Example
deleteDocs()
deleteDocs(Deletes documents from an index by their IDs asynchronously. The index rebuild happens server-side. This method polls until the rebuild is complete and then returns.indexName,docIds,options?):Promise<MutationResult>
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the target index. |
docIds | string[] | Array of document IDs to delete. |
options? | MutationOptions | Optional configuration (onProgress callback). |
Returns
Promise<MutationResult>
Promise that resolves to MutationResult when the operation is complete.
Throws
If the index does not exist.Example
getJobStatus()
getJobStatus(Gets the current status of an async job.jobId):Promise<JobStatusResponse>
Parameters
| Parameter | Type | Description |
|---|---|---|
jobId | string | The job ID returned by createIndex, addDocs, or deleteDocs. |
Returns
Promise<JobStatusResponse>
Promise that resolves to JobStatusResponse with progress details.
Example
getDocs()
getDocs(Retrieves documents from an index.indexName,options?):Promise<DocumentInfo[]>
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the target index. |
options? | GetDocumentsOptions | Optional configuration for retrieval. |
Returns
Promise<DocumentInfo[]>
Promise that resolves to array of documents.
Throws
If the index does not exist.Example
loadIndex()
loadIndex(Downloads an index from the cloud into memory for fast local querying. How it works:indexName,options?):Promise<string>
- Fetches the index assets from the cloud
- Loads the embedding model for generating query embeddings
- Executes a local similarity match between the query embedding and the retrieved index.
query() it. Once loaded, queries run entirely in-memory (~1-10ms).
Reload behavior:
If the index is already loaded, calling loadIndex() again will:
- Stop any existing auto-refresh polling
- Download a fresh copy from the cloud
- Replace the in-memory index
autoRefresh: true to periodically poll the cloud for updates.
When a newer version is detected, the index is automatically hot-swapped
without interrupting queries.
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the index to load. |
options? | LoadIndexOptions | Optional configuration including auto-refresh settings. |
Returns
Promise<string>
Promise that resolves to the index name.
Throws
If the index does not exist in the cloud or loading fails.Example
query()
query(Performs a semantic similarity search against a loaded index. CallindexName,query,options?):Promise<SearchResult>
loadIndex() first;
queries then run entirely in-memory. Metadata filtering is supported on loaded indexes.
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Name of the target index to search. |
query | string | The search query text. |
options? | QueryOptions | Optional query configuration including topK (default: 5) and embedding overrides. |
Returns
Promise<SearchResult>
Promise that resolves to SearchResult with matching documents.
Throws
If the specified index does not exist.Example
getAuthToken()
getAuthToken():Returns a short-lived auth token for the current project. This is primarily useful for custom-authenticator patterns, where your backend mints tokens for untrusted clients instead of shipping thePromise<AuthToken>
projectKey. See the
Custom Authenticator guide for details.
Returns
Promise<AuthToken>
Promise that resolves to an AuthToken containing the token string and its
expiresIn lifetime in seconds.
Example
session()
session(Creates or resumes a local-firstindexName,modelId?):Promise<SessionIndex>
SessionIndex. If a cloud index with the
given name already exists it is loaded into the session (no re-embedding); otherwise the
session starts empty. The indexName is also the target when
pushIndex() is called.
Requires a client constructed with a project key. Calling session() on a client built with
a custom IAuthenticator throws.
Parameters
| Parameter | Type | Description |
|---|---|---|
indexName | string | Cloud index name to create, resume, and push to. |
modelId? | MossModel | Embedding model for the session. Default "moss-minilm". Other options: "moss-mediumlm", "custom". |
Returns
Promise<SessionIndex>