Rerankers

Methods on this page are called as client.rerankers.<method>(...) on a Goodmem instance.

Class — ai.pairsys.goodmem.client.api.RerankersAPI (extends internal RerankersAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

try (Goodmem client = Goodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    // client.rerankers.<method>(...)
}

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncRerankersAPI (accessed via asyncClient.rerankers on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>. See the async client guide for composition patterns.

import ai.pairsys.goodmem.client.AsyncGoodmem;

try (AsyncGoodmem asyncClient = AsyncGoodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    asyncClient.rerankers.<method>(...)  // returns CompletableFuture<T>
}

Method Detail

`create(RerankerCreationRequest)`

RerankerResponse create(RerankerCreationRequest request)

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.

Convenience override: applies declarative transforms (registry lookup / endpoint inference / default injection / credential check as declared in convenience.json) before forwarding to the raw Tier-2 request. Any field already set on request wins over registry values.

HTTP — POST /v1/rerankers

Parameters

request (RerankerCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — RerankerResponse

Example

RerankerResponse rerankerResponse = client.rerankers.create(RerankerCreationRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/rerankers' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc Reranker",
    "modelIdentifier": "rerank-2",
    "labels": {
      "env": "docs"
    },
    "credentials": {
      "kind": "CREDENTIAL_KIND_API_KEY",
      "apiKey": {
        "inlineSecret": "voyage-key-..."
      }
    },
    "providerType": "VOYAGE",
    "supportedModalities": [
      "TEXT"
    ],
    "endpointUrl": "https://api.voyageai.com/v1"
  }'

`create(RerankerCreationRequest, String)`

RerankerResponse create(RerankerCreationRequest request, String apiKey)

Convenience overload: auto-fills provider / endpoint / dimensionality from the bundled model registry keyed by modelIdentifier, and converts a bare apiKey string to the structured EndpointAuthentication. Pass null for apiKey to preserve request.credentials(). Any field already set on request wins over registry values.

HTTP — POST /v1/rerankers

Parameters

request (RerankerCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.
apiKey (String, optional) — bare API key for the upstream provider. Converted to EndpointAuthentication via Transforms.apiKeyToCredentials. Pass null to preserve request.credentials().

Returns — RerankerResponse

Example

RerankerResponse rerankerResponse = client.rerankers.create(RerankerCreationRequest.builder()
            // …set required fields…
            .build(), "<provider-api-key>");

REST equivalent

curl -X POST 'http://localhost:8080/v1/rerankers' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc Reranker",
    "modelIdentifier": "rerank-2",
    "labels": {
      "env": "docs"
    },
    "credentials": {
      "kind": "CREDENTIAL_KIND_API_KEY",
      "apiKey": {
        "inlineSecret": "voyage-key-..."
      }
    },
    "providerType": "VOYAGE",
    "supportedModalities": [
      "TEXT"
    ],
    "endpointUrl": "https://api.voyageai.com/v1"
  }'

`delete(String)`

void delete(String id)

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.

HTTP — DELETE /v1/rerankers/{id}

Parameters

id (String) — The unique identifier of the reranker to delete

Returns — None (HTTP 204).

Example

client.rerankers.delete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/rerankers/{id}' \
  -H "x-api-key: gm_..."

`get(String)`

RerankerResponse get(String id)

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.

HTTP — GET /v1/rerankers/{id}

Parameters

id (String) — The unique identifier of the reranker to retrieve

Returns — RerankerResponse

Example

RerankerResponse rerankerResponse = client.rerankers.get("...");

REST equivalent

curl -X GET 'http://localhost:8080/v1/rerankers/{id}' \
  -H "x-api-key: gm_..."

`list(RerankerListOptions)`

List<RerankerResponse> list(RerankerListOptions options)

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.

HTTP — GET /v1/rerankers

Parameters

options (RerankerListOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — List``<RerankerResponse>

Example

List<RerankerResponse> list = client.rerankers.list(RerankerListOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/rerankers' \
  -H "x-api-key: gm_..."

`update(String, UpdateRerankerRequest)`

RerankerResponse update(String id, UpdateRerankerRequest request)

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.

HTTP — PUT /v1/rerankers/{id}

Parameters

id (String) — The unique identifier of the reranker to update
request (UpdateRerankerRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — RerankerResponse

Example

RerankerResponse rerankerResponse = client.rerankers.update("...", UpdateRerankerRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/rerankers/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc Reranker (updated)",
    "mergeLabels": {
      "version": "2"
    }
  }'

Errors

Every method on this page may throw the standard HTTP-error class hierarchy rooted at GoodmemException:

BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx), or the generic ApiException for any other 4xx/5xx. All are unchecked (RuntimeException). See Errors.

All error classes live in ai.pairsys.goodmem.client.errors and are unchecked (RuntimeException). Async siblings complete the returned CompletableFuture exceptionally with the same types, wrapped in CompletionException at await time. See Errors on the index for the full table.

Rerankers

On this page