Embedders

Embedder management — provider configuration + lifecycle.

Namespace: Goodmem.Client.Api · Class: EmbeddersApi

Reach this surface as client.Embedders on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.

Methods

CreateAsync

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).

Declaration

public Task<EmbedderResponse> CreateAsync(EmbedderCreationRequest request, string? apiKey = null, CancellationToken ct = default)

HTTP — POST /v1/embedders

Parameters

Returns

Task<EmbedderResponse> — an awaitable that resolves to EmbedderResponse.

Exceptions

Example

var embedder = await client.Embedders.CreateAsync(
    new EmbedderCreationRequest
    {
        DisplayName = "Doc Embedder",
        ModelIdentifier = "text-embedding-3-small",
        Labels = new Dictionary<string, string> { ["env"] = "docs" },
    },
    "sk-..."
);
Console.WriteLine(embedder.EmbedderId);

GetAsync

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.

Declaration

public Task<EmbedderResponse> GetAsync(string id, CancellationToken ct = default)

HTTP — GET /v1/embedders/{id}

Parameters

Returns

Task<EmbedderResponse> — an awaitable that resolves to EmbedderResponse.

Exceptions

Example

var embedder = await client.Embedders.GetAsync("your-embedder-id");
Console.WriteLine(embedder.DisplayName);

ListAsync

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.

Declaration

public Task<ListEmbeddersResponse> ListAsync(EmbeddersListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/embedders

Parameters

Returns

Task<ListEmbeddersResponse> — an awaitable that resolves to ListEmbeddersResponse.

Exceptions

Example

var resp = await client.Embedders.ListAsync();
foreach (var embedder in resp.Embedders)
    Console.WriteLine($"{embedder.EmbedderId} {embedder.DisplayName}");

UpdateAsync

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).

Declaration

public Task<EmbedderResponse> UpdateAsync(string id, UpdateEmbedderRequest request, CancellationToken ct = default)

HTTP — PUT /v1/embedders/{id}

Parameters

Returns

Task<EmbedderResponse> — an awaitable that resolves to EmbedderResponse.

Exceptions

Example

var updated = await client.Embedders.UpdateAsync(
    "your-embedder-id",
    new UpdateEmbedderRequest
    {
        DisplayName = "Doc Embedder (updated)",
        MergeLabels = new Dictionary<string, string> { ["version"] = "2" },
    }
);
Console.WriteLine(updated.EmbedderId);

DeleteAsync

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).

Declaration

public Task DeleteAsync(string id, CancellationToken ct = default)

HTTP — DELETE /v1/embedders/{id}

Parameters

Returns

Task — completes when the operation finishes; there is no response body.

Exceptions

Example

await client.Embedders.DeleteAsync("your-embedder-id");

Data Models

Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.

EmbedderCreationRequest

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

DistributionType

Type of embedding distribution produced by the embedder

String enum: "DENSE" · "SPARSE"

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.