Embedders

Embedder management.

Methods on this page are called through client.embedders.

client.embedders.create

client.embedders.create(request: EmbeddersCreateRequest, requestOptions?: ProviderApiKeyOptions): Promise<EmbedderResponseShape>

Creates a new embedder configuration for vectorizing content. Embedders represent connections to different embedding API services (like OpenAI, vLLM, etc.) and include all the necessary configuration to use them with memory spaces. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another embedder exists with identical {ownerId, providerType, endpointUrl, apiPath, modelIdentifier, dimensionality, distributionType, credentialsFingerprint} after URL canonicalization. Uniqueness is enforced per-owner, allowing different users to have identical configurations. Credentials are hashed (SHA-256) for uniqueness while remaining encrypted. The apiPath field defaults to '/v2/embed' for Cohere, '/embed' for TEI, and '/embeddings' for other providers when omitted. Requires CREATE_EMBEDDER_OWN permission (or CREATE_EMBEDDER_ANY for admin users).

HTTP: POST /v1/embedders

Parameters

Returns: Promise<EmbedderResponseShape>

Example

const embedder = await client.embedders.create(
  {
    displayName: "Doc Embedder",
    modelIdentifier: "text-embedding-3-small",
    labels: { env: "docs" },
  },
  { apiKey: "sk-..." },
);

client.embedders.delete

client.embedders.delete(id: string, requestOptions?: RequestOptions): Promise<void>

Permanently deletes an embedder configuration. This operation cannot be undone and removes the embedder record and securely deletes stored credentials. IMPORTANT: This does NOT invalidate or delete embeddings previously created with this embedder - existing embeddings remain accessible. CONFLICT: Returns HTTP 409 Conflict if the embedder is still referenced by a space. Requires DELETE_EMBEDDER_OWN permission for embedders you own (or DELETE_EMBEDDER_ANY for admin users).

HTTP: DELETE /v1/embedders/{id}

Parameters

Returns: Promise<void>

Example

await client.embedders.delete("your-embedder-id");

client.embedders.get

client.embedders.get(id: string, requestOptions?: RequestOptions): Promise<EmbedderResponseShape>

Retrieves the details of a specific embedder configuration by its unique identifier. Requires READ_EMBEDDER_OWN permission for embedders you own (or READ_EMBEDDER_ANY for admin users to view any user's embedders). This is a read-only operation with no side effects.

HTTP: GET /v1/embedders/{id}

Parameters

Returns: Promise<EmbedderResponseShape>

Example

const fetchedEmbedder = await client.embedders.get("your-embedder-id");
console.log(fetchedEmbedder.displayName);

client.embedders.list

client.embedders.list(options?: EmbeddersListOptions, requestOptions?: RequestOptions): Promise<Array<EmbedderResponseShape>>

Retrieves a list of embedder configurations accessible to the caller, with optional filtering. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production). PERMISSION-BASED FILTERING: With LIST_EMBEDDER_OWN permission, you can only see your own embedders (ownerId filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any ownerId. This is a read-only operation with no side effects.

HTTP: GET /v1/embedders

Parameters

Returns: Promise<Array<EmbedderResponseShape>>

Example

for (const emb of await client.embedders.list()) {
  console.log(emb.embedderId, emb.displayName);
}

client.embedders.update

client.embedders.update(id: string, request: UpdateEmbedderRequest, requestOptions?: RequestOptions): Promise<EmbedderResponseShape>

Updates an existing embedder configuration including display information, endpoint configuration, model parameters, credentials, and labels. All fields are optional - only specified fields will be updated. IMPORTANT: providerType is IMMUTABLE after creation and cannot be changed. CRITICAL: Returns HTTP 412 Precondition Failed (FAILED_PRECONDITION) if attempting to update core fields (dimensionality, distributionType, modelIdentifier) while the embedder is actively referenced by spaces or ingestion jobs. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if the update would create a duplicate embedder with the same provider, endpoint, model, dimensionality, distribution, and credentials for this owner. Requires UPDATE_EMBEDDER_OWN permission for embedders you own (or UPDATE_EMBEDDER_ANY for admin users).

HTTP: PUT /v1/embedders/{id}

Parameters

Returns: Promise<EmbedderResponseShape>

Example

const updatedEmbedder = await client.embedders.update("your-embedder-id", {
  displayName: "Doc Embedder (updated)",
  mergeLabels: { version: "2" },
});
console.log(updatedEmbedder.embedderId);

Data Models

Enum Values

DistributionType

DENSE, SPARSE

Interfaces

EmbedderCreationRequest

Request body for creating a new Embedder. An Embedder represents a configuration for vectorizing content.

EmbedderResponse

Embedder configuration information

ListEmbeddersResponse

Response containing a list of embedders

UpdateEmbedderRequest

Request body for updating an existing Embedder. Only fields that should be updated need to be included. supportedModalities is creation-time only and cannot be changed here.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

EmbedderResponseShape

ListEmbeddersResponseShape