GoodMem
ReferenceClient SDKsJava SDK

Rerankers API

Rerankers API documentation for Java SDK

The default url is https://localhost:8080

MethodHTTP requestDescription
createRerankerPOST /v1/rerankersCreate a new reranker
deleteRerankerDELETE /v1/rerankers/{id}Delete a reranker
getRerankerGET /v1/rerankers/{id}Get a reranker by ID
listRerankersGET /v1/rerankersList rerankers
updateRerankerPUT /v1/rerankers/{id}Update a reranker

createReranker

RerankerResponse createReranker(rerankerCreationRequest)

Create a new reranker

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.

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.RerankersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    RerankersApi apiInstance = new RerankersApi(defaultClient);
    RerankerCreationRequest rerankerCreationRequest = new RerankerCreationRequest(); // RerankerCreationRequest | Reranker configuration details
    try {
      RerankerResponse result = apiInstance.createReranker(rerankerCreationRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling RerankersApi#createReranker");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
rerankerCreationRequestRerankerCreationRequestReranker configuration details

Return type

RerankerResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
201Successfully created reranker with Location header* Location - URL of the created reranker resource
400Invalid request - missing required fields or invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to create rerankers-
409Conflict - reranker already exists with identical ownerId, providerType, endpointUrl, apiPath, modelIdentifier, and credentialsFingerprint-

deleteReranker

deleteReranker(id)

Delete a reranker

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.

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.RerankersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    RerankersApi apiInstance = new RerankersApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the reranker to delete
    try {
      apiInstance.deleteReranker(id);
    } catch (ApiException e) {
      System.err.println("Exception when calling RerankersApi#deleteReranker");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the reranker to delete

Return type

null (empty response body)

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

HTTP response details

Status codeDescriptionResponse headers
204Reranker successfully deleted-
400Invalid request - reranker ID in invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to delete this reranker-
404Not found - reranker with the specified ID does not exist-

getReranker

RerankerResponse getReranker(id)

Get a reranker by 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.

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.RerankersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    RerankersApi apiInstance = new RerankersApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the reranker to retrieve
    try {
      RerankerResponse result = apiInstance.getReranker(id);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling RerankersApi#getReranker");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the reranker to retrieve

Return type

RerankerResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully retrieved reranker-
400Invalid request - reranker ID in invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to view this reranker-
404Not found - reranker with the specified ID does not exist-

listRerankers

ListRerankersResponse listRerankers(ownerId, providerType, labelStar)

List rerankers

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

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.RerankersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    RerankersApi apiInstance = new RerankersApi(defaultClient);
    String ownerId = "550e8400-e29b-41d4-a716-446655440000"; // String | Filter rerankers by owner ID. With LIST_RERANKER_ANY permission, omitting this shows all accessible rerankers; providing it filters by that owner. With LIST_RERANKER_OWN permission, only your own rerankers are shown regardless of this parameter (PERMISSION_DENIED if set to another user).
    String providerType = "TEI"; // String | Filter rerankers by provider type (e.g., OPENAI, TEI, VLLM, etc.)
    String labelStar = "?label.environment=production&label.team=search"; // String | Filter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=search)
    try {
      ListRerankersResponse result = apiInstance.listRerankers(ownerId, providerType, labelStar);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling RerankersApi#listRerankers");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
ownerIdStringFilter rerankers by owner ID. With LIST_RERANKER_ANY permission, omitting this shows all accessible rerankers; providing it filters by that owner. With LIST_RERANKER_OWN permission, only your own rerankers are shown regardless of this parameter (PERMISSION_DENIED if set to another user).[optional]
providerTypeStringFilter rerankers by provider type (e.g., OPENAI, TEI, VLLM, etc.)[optional]
labelStarStringFilter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=search)[optional]

Return type

ListRerankersResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully retrieved rerankers-
400Invalid request - invalid filter parameters or pagination token-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to list rerankers-

updateReranker

RerankerResponse updateReranker(id, updateRerankerRequest)

Update a reranker

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

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.RerankersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    RerankersApi apiInstance = new RerankersApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the reranker to update
    UpdateRerankerRequest updateRerankerRequest = new UpdateRerankerRequest(); // UpdateRerankerRequest | Updated reranker configuration details
    try {
      RerankerResponse result = apiInstance.updateReranker(id, updateRerankerRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling RerankersApi#updateReranker");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the reranker to update
updateRerankerRequestUpdateRerankerRequestUpdated reranker configuration details

Return type

RerankerResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully updated reranker-
400Invalid request - invalid fields or label strategy conflict-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to update this reranker-
404Not found - reranker with the specified ID does not exist-
409Conflict - update would create duplicate with same ownerId, providerType, endpointUrl, apiPath, modelIdentifier, and credentialsFingerprint after URL canonicalization-

Ping API

Ping API documentation for Java SDK

Spaces API

Spaces API documentation for Java SDK

On this page

createRerankerExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsdeleteRerankerExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsgetRerankerExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailslistRerankersExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsupdateRerankerExampleParametersReturn typeAuthorizationHTTP request headersHTTP response details