Rerankers API

The default url is http://localhost:8080

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 GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.RerankersApi();
let rerankerCreationRequest = {"displayName":"BGE Cross-Encoder Reranker","description":"BAAI BGE reranker for cross-encoder semantic ranking","providerType":"TEI","endpointUrl":"http://bge.reranker.goodmem.ai:8010","apiPath":"/rerank","modelIdentifier":"BAAI/bge-reranker-base","supportedModalities":["TEXT"],"credentials":{"kind":"CREDENTIAL_KIND_API_KEY","apiKey":{"inlineSecret":"sk-demo-api-key"}},"labels":{"environment":"production","team":"search"}}; // RerankerCreationRequest | Reranker configuration details
apiInstance.createReranker(rerankerCreationRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Return type

RerankerResponse

Authorization

No authorization required

HTTP request headers

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

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 GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.RerankersApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the reranker to delete
apiInstance.deleteReranker(id).then(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

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

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 GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.RerankersApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the reranker to retrieve
apiInstance.getReranker(id).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Return type

RerankerResponse

Authorization

No authorization required

HTTP request headers

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

listRerankers

ListRerankersResponse listRerankers(opts)

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 GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.RerankersApi();
let opts = {
  '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).
  'providerType': "TEI", // String | Filter rerankers by provider type (e.g., OPENAI, TEI, VLLM, etc.)
  'label': "?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)
};
apiInstance.listRerankers(opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Return type

ListRerankersResponse

Authorization

No authorization required

HTTP request headers

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

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 GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.RerankersApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the reranker to update
let updateRerankerRequest = {"displayName":"Updated Production BGE Reranker","description":"Updated BAAI BGE cross-encoder reranker with enhanced configuration for production use","endpointUrl":"http://bge.reranker.goodmem.ai:8010","apiPath":"/rerank","modelIdentifier":"BAAI/bge-reranker-large","supportedModalities":["TEXT"],"credentials":{"kind":"CREDENTIAL_KIND_API_KEY","apiKey":{"inlineSecret":"updated-api-key-here"}},"version":"2.1.0","monitoringEndpoint":"https://monitoring.company.com/rerankers/status","replaceLabels":{"environment":"production","team":"search-platform","cost-center":"ml-infrastructure"}}; // UpdateRerankerRequest | Updated reranker configuration details
apiInstance.updateReranker(id, updateRerankerRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Return type

RerankerResponse

Authorization

No authorization required

HTTP request headers

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