GoodMem
ReferenceClient SDKsPython SDK

Rerankers API

Rerankers API documentation for Python SDK

All URIs are relative to http://localhost:8080

MethodHTTP requestDescription
create_rerankerPOST /v1/rerankersCreate a new reranker
delete_rerankerDELETE /v1/rerankers/{id}Delete a reranker
get_rerankerGET /v1/rerankers/{id}Get a reranker by ID
list_rerankersGET /v1/rerankersList rerankers
update_rerankerPUT /v1/rerankers/{id}Update a reranker

create_reranker

RerankerResponse create_reranker(reranker_creation_request)

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 ALREADY_EXISTS if another reranker exists with identical {owner_id, provider_type, endpoint_url, api_path, model_identifier, credentials_fingerprint} 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: api_path defaults to '/rerank' if omitted; supported_modalities 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

  • Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.reranker_creation_request import RerankerCreationRequest
from goodmem_client.models.reranker_response import RerankerResponse
from goodmem_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
    host = "http://localhost:8080/v1/default"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = goodmem_client.RerankersApi(api_client)
    reranker_creation_request = {"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

    try:
        # Create a new reranker
        api_response = api_instance.create_reranker(reranker_creation_request)
        print("The response of RerankersApi->create_reranker:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling RerankersApi->create_reranker: %s\n" % e)

Parameters

NameTypeDescriptionNotes
reranker_creation_requestRerankerCreationRequestReranker 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 owner_id, provider_type, endpoint_url, api_path, model_identifier, and credentials_fingerprint-

↑ Back to Python SDK

delete_reranker

delete_reranker(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

  • Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
    host = "http://localhost:8080/v1/default"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = goodmem_client.RerankersApi(api_client)
    id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the reranker to delete

    try:
        # Delete a reranker
        api_instance.delete_reranker(id)
    except Exception as e:
        print("Exception when calling RerankersApi->delete_reranker: %s\n" % e)

Parameters

NameTypeDescriptionNotes
idstrThe unique identifier of the reranker to delete

Return type

void (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-

↑ Back to Python SDK

get_reranker

RerankerResponse get_reranker(id)

Get a reranker by ID

Retrieves the details of a specific reranker configuration by its unique identifier. SECURITY NOTE: The credentials field is omitted from the response for security reasons. 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

  • Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.reranker_response import RerankerResponse
from goodmem_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
    host = "http://localhost:8080/v1/default"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = goodmem_client.RerankersApi(api_client)
    id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the reranker to retrieve

    try:
        # Get a reranker by ID
        api_response = api_instance.get_reranker(id)
        print("The response of RerankersApi->get_reranker:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling RerankersApi->get_reranker: %s\n" % e)

Parameters

NameTypeDescriptionNotes
idstrThe 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-

↑ Back to Python SDK

list_rerankers

ListRerankersResponse list_rerankers(owner_id=owner_id, provider_type=provider_type, label_=label_)

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. SECURITY NOTE: credentials fields are omitted from all responses. 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 owner_id. Specifying owner_id without LIST_RERANKER_ANY permission returns PERMISSION_DENIED.

Example

  • Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.list_rerankers_response import ListRerankersResponse
from goodmem_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
    host = "http://localhost:8080/v1/default"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = goodmem_client.RerankersApi(api_client)
    owner_id = '550e8400-e29b-41d4-a716-446655440000' # str | 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). (optional)
    provider_type = 'TEI' # str | Filter rerankers by provider type (e.g., OPENAI, TEI, VLLM, etc.) (optional)
    label_ = '?label.environment=production&label.team=search' # str | Filter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=search) (optional)

    try:
        # List rerankers
        api_response = api_instance.list_rerankers(owner_id=owner_id, provider_type=provider_type, label_=label_)
        print("The response of RerankersApi->list_rerankers:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling RerankersApi->list_rerankers: %s\n" % e)

Parameters

NameTypeDescriptionNotes
owner_idstrFilter 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]
provider_typestrFilter rerankers by provider type (e.g., OPENAI, TEI, VLLM, etc.)[optional]
label_strFilter 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-

↑ Back to Python SDK

update_reranker

RerankerResponse update_reranker(id, update_reranker_request)

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: provider_type and owner_id 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 {endpoint_url, api_path, model_identifier}. Requires UPDATE_RERANKER_OWN permission for rerankers you own (or UPDATE_RERANKER_ANY for admin users). This operation is idempotent.

Example

  • Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.reranker_response import RerankerResponse
from goodmem_client.models.update_reranker_request import UpdateRerankerRequest
from goodmem_client.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
    host = "http://localhost:8080/v1/default"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = goodmem_client.RerankersApi(api_client)
    id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the reranker to update
    update_reranker_request = {"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

    try:
        # Update a reranker
        api_response = api_instance.update_reranker(id, update_reranker_request)
        print("The response of RerankersApi->update_reranker:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling RerankersApi->update_reranker: %s\n" % e)

Parameters

NameTypeDescriptionNotes
idstrThe unique identifier of the reranker to update
update_reranker_requestUpdateRerankerRequestUpdated 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 endpoint_url, api_path, and model_identifier-

↑ Back to Python SDK