Skip to main content
@moss-js/moss / MossClient

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

Model responses grounded in your indexes come from a separate client, MossInference, not from MossClient. See Inference.

Constructors

Constructor

new MossClient(projectId, projectKey, options?): MossClient
Creates a new MossClient instance.

Parameters

Returns

MossClient

Constructor (custom authenticator)

new MossClient(projectId, authenticator, options?): MossClient
Creates a new MossClient instance with a custom authenticator. Use this pattern from browser or untrusted clients where the projectKey must never be embedded in shipped code. See the Custom Authenticator guide for details.

Parameters

MossClientOptions

The optional last argument of both constructors.

Methods

createIndex()

createIndex(indexName, docs, options?): Promise<MutationResult>
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.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the index is ready.

Throws

If the index already exists or creation fails.

Example


createIndexFromFiles()

createIndexFromFiles(indexName, files, options?): Promise<MutationResult>
Creates a new index by uploading raw files for server-side parsing and embedding. Handles the full flow: init, upload files, confirm, then poll until complete. Returns when the index is ready. Supported file types are PDF and DOCX. See the Index from Files guide for parse options, limits, and querying notes.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the index is ready.

Throws

If files is empty, exceeds 20 files, has an unsupported contentType, uses modelId: 'custom', or creation fails.

Example


getIndex()

getIndex(indexName): Promise<IndexInfo>
Gets information about a specific index.

Parameters

Returns

Promise<IndexInfo> Promise that resolves to IndexInfo object.

Throws

If the index does not exist.

Example


listIndexes()

listIndexes(): Promise<IndexInfo[]>
Lists all available indexes.

Returns

Promise<IndexInfo[]> Promise that resolves to array of IndexInfo objects.

Example


deleteIndex()

deleteIndex(indexName): Promise<boolean>
Deletes an index and all its data.

Parameters

Returns

Promise<boolean> Promise that resolves to true if successful.

Throws

If the index does not exist.

Example


addDocs()

addDocs(indexName, docs, options?): Promise<MutationResult>
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.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example


deleteDocs()

deleteDocs(indexName, docIds, options?): Promise<MutationResult>
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.

Parameters

Returns

Promise<MutationResult> Promise that resolves to MutationResult when the operation is complete.

Throws

If the index does not exist.

Example


getJobStatus()

getJobStatus(jobId): Promise<JobStatusResponse>
Gets the current status of an async job.

Parameters

Returns

Promise<JobStatusResponse> Promise that resolves to JobStatusResponse with progress details.

Example


getDocs()

getDocs(indexName, options?): Promise<DocumentInfo[]>
Retrieves documents from an index.

Parameters

Returns

Promise<DocumentInfo[]> Promise that resolves to array of documents.

Throws

If the index does not exist.

Example


loadIndex()

loadIndex(indexName, options?): Promise<string>
Downloads an index from the cloud into memory for fast local querying. How it works:
  1. Fetches the index assets from the cloud
  2. Loads the embedding model for generating query embeddings
  3. Executes a local similarity match between the query embedding and the retrieved index.
Why use this? An index must be loaded before you can 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
Auto-refresh (optional): Enable 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

Returns

Promise<string> Promise that resolves to the index name.

Throws

If the index does not exist in the cloud or loading fails.

Example


loadIndexes()

loadIndexes(indexNames, options?): Promise<LoadIndexesResult>
Loads several indexes into memory in one call. A name that fails to load is reported in failed and does not affect the others.

Parameters

Returns

Promise<LoadIndexesResult> { loaded, failed, failedCodes }: failed maps a name to its error message, and failedCodes maps it to its MossErrorCode.

Example


unloadIndex()

unloadIndex(indexName): Promise<void>
Removes a loaded index from memory and stops its auto-refresh polling.

Parameters

Returns

Promise<void>

Example


unloadIndexes()

unloadIndexes(indexNames): Promise<void>
Removes several loaded indexes from memory. Names that are not loaded are ignored.

Parameters

Returns

Promise<void>

Example


query()

query(indexName, query, options?): Promise<SearchResult>
Performs a semantic similarity search against a loaded index. Call loadIndex() first; queries then run entirely in-memory. Metadata filtering is supported on loaded indexes.

Parameters

Returns

Promise<SearchResult> Promise that resolves to SearchResult with matching documents.

Throws

If the specified index does not exist.

Example


queryMultiIndex()

queryMultiIndex(indexNames, query, options?): Promise<SearchResult>
Searches several loaded indexes in one call and returns the global top-k, with each result’s indexName set to its source index. All indexes must already be loaded and share the same embedding model.

Parameters

Returns

Promise<SearchResult> SearchResult whose docs carry indexName.

Throws

If no names are given, a name is not loaded, or models differ.

Example


getAuthToken()

getAuthToken(): Promise<AuthToken>
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 the 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(indexName, modelId?, modelArtifact?): Promise<SessionIndex>
Creates a local-first SessionIndex. The session starts empty, even when a cloud index with the given name exists; call session.loadIndex(indexName) to pull that index in without re-embedding. The indexName is also the target when pushIndex() is called. Works with a client built with either a project key or a custom IAuthenticator. With a project key, the session exchanges the key for an access token when it opens, and the promise rejects if the key is invalid. With a custom IAuthenticator, the session gets its tokens through the same bridge as loadIndex(). For a built-in model, opening the session also loads the embedding model, which calls Moss with that token, so the promise rejects if the authenticator fails or Moss refuses its token. With a custom IAuthenticator and the "custom" model, opening asks the authenticator for a token but makes no call to Moss, so a token Moss refuses first surfaces on session.loadIndex() or pushIndex().

Parameters

Returns

Promise<SessionIndex>

Example


close()

close(): Promise<void>
Sends the final usage report, then releases the client’s native resources: its loaded indexes, refresh pollers and telemetry. Also closes every session the client opened. Resolves once the report arrives or 2 seconds pass. Safe to call more than once; concurrent callers share one promise. Afterwards every method rejects with MossClient is closed; create a new client to continue. MossClient also implements Symbol.asyncDispose, so await using closes it when the enclosing block ends (Node.js 24 or later).

Returns

Promise<void>

Example

See Releasing resources.