Rerankers

Reranker management — re-scoring of retrieval hits.

Namespace: Goodmem.Client.Api · Class: RerankersApi

Reach this surface as client.Rerankers 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 reranker configuration for ranking search results. Rerankers represent connections to different reranking API services (like TEI, OpenAI, etc.) and include all the necessary configuration to use them for result ranking. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another reranker exists with identical {ownerId, providerType, endpointUrl, apiPath, modelIdentifier, 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. DEFAULTS: apiPath defaults to '/v2/rerank' for Cohere and '/rerank' for other providers if omitted; supportedModalities defaults to [TEXT] if omitted. Requires CREATE_RERANKER_OWN permission (or CREATE_RERANKER_ANY for admin users). This operation is NOT idempotent - each request creates a new reranker record.

Declaration

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

HTTP — POST /v1/rerankers

Parameters

Returns

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

Exceptions

Example

var reranker = await client.Rerankers.CreateAsync(
    new RerankerCreationRequest
    {
        DisplayName = "Doc Reranker",
        ModelIdentifier = "rerank-2",
        Labels = new Dictionary<string, string> { ["env"] = "docs" },
    },
    "voyage-key-..."
);
Console.WriteLine(reranker.RerankerId);

GetAsync

Retrieves the details of a specific reranker configuration by its unique identifier. Response payloads include stored credentials, matching gRPC response semantics. Requires READ_RERANKER_OWN permission for rerankers you own (or READ_RERANKER_ANY for admin users). This is a read-only operation with no side effects and is safe to retry.

Declaration

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

HTTP — GET /v1/rerankers/{id}

Parameters

Returns

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

Exceptions

Example

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

ListAsync

Retrieves a list of reranker configurations accessible to the caller, with optional filtering. IMPORTANT: Pagination is NOT supported - all matching results are returned. Results are ordered by created_at descending. Responses include stored credentials, matching gRPC response semantics. 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_RERANKER_OWN permission, only your own rerankers are shown. With LIST_RERANKER_ANY permission, you can see all rerankers or filter by any ownerId. Specifying ownerId without LIST_RERANKER_ANY permission returns PERMISSION_DENIED.

Declaration

public Task<ListRerankersResponse> ListAsync(RerankersListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/rerankers

Parameters

Returns

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

Exceptions

Example

var resp = await client.Rerankers.ListAsync();
foreach (var reranker in resp.Rerankers)
    Console.WriteLine($"{reranker.RerankerId} {reranker.DisplayName}");

UpdateAsync

Updates an existing reranker configuration including display information, endpoint configuration, model parameters, credentials, and labels. All fields are optional - only specified fields will be updated. IMMUTABLE FIELDS: providerType and ownerId cannot be changed after creation. SUPPORTED_MODALITIES UPDATE: If the array contains >=1 elements, it replaces the stored set; if empty or omitted, no change occurs and it does not count as an update by itself. Returns ALREADY_EXISTS if update would create duplicate with same {ownerId, providerType, endpointUrl, apiPath, modelIdentifier, credentialsFingerprint} after URL canonicalization (HTTP 409 Conflict / ALREADY_EXISTS). Requires UPDATE_RERANKER_OWN permission for rerankers you own (or UPDATE_RERANKER_ANY for admin users). This operation is idempotent.

Declaration

public Task<RerankerResponse> UpdateAsync(string id, UpdateRerankerRequest request, CancellationToken ct = default)

HTTP — PUT /v1/rerankers/{id}

Parameters

Returns

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

Exceptions

Example

var updated = await client.Rerankers.UpdateAsync(
    "your-reranker-id",
    new UpdateRerankerRequest
    {
        DisplayName = "Doc Reranker (updated)",
        MergeLabels = new Dictionary<string, string> { ["version"] = "2" },
    }
);
Console.WriteLine(updated.RerankerId);

DeleteAsync

Permanently deletes a reranker configuration. This operation cannot be undone and immediately removes the reranker record from the database. SIDE EFFECTS: Invalidates any cached references to this reranker; does not affect historical usage data or audit logs. Requires DELETE_RERANKER_OWN permission for rerankers you own (or DELETE_RERANKER_ANY for admin users). This operation is safe to retry - may return NOT_FOUND if already deleted.

Declaration

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

HTTP — DELETE /v1/rerankers/{id}

Parameters

Returns

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

Exceptions

Example

await client.Rerankers.DeleteAsync("your-reranker-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.

RerankerCreationRequest

Request body for creating a new Reranker. A Reranker represents a configuration for reranking search results.

RerankerResponse

Reranker configuration information

ListRerankersResponse

Response containing a list of rerankers

UpdateRerankerRequest

Request body for updating an existing Reranker. Only fields that should be updated need to be included. supportedModalities replaces the stored set only when the array contains at least one value; empty or omitted leaves it unchanged and does not count as an update by itself.