Rerankers API
Rerankers API documentation for Python SDK
All URIs are relative to http://localhost:8080
| Method | HTTP request | Description |
|---|---|---|
| create_reranker | POST /v1/rerankers | Create a new reranker |
| delete_reranker | DELETE /v1/rerankers/{id} | Delete a reranker |
| get_reranker | GET /v1/rerankers/{id} | Get a reranker by ID |
| list_rerankers | GET /v1/rerankers | List rerankers |
| update_reranker | PUT /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
| Name | Type | Description | Notes |
|---|---|---|---|
| reranker_creation_request | RerankerCreationRequest | Reranker configuration details |
Return type
Authorization
HTTP request headers
- Content-Type: application/json
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 201 | Successfully created reranker with Location header | * Location - URL of the created reranker resource |
| 400 | Invalid request - missing required fields or invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to create rerankers | - |
| 409 | Conflict - reranker already exists with identical owner_id, provider_type, endpoint_url, api_path, model_identifier, and credentials_fingerprint | - |
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the reranker to delete |
Return type
void (empty response body)
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: Not defined
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 204 | Reranker successfully deleted | - |
| 400 | Invalid request - reranker ID in invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to delete this reranker | - |
| 404 | Not found - reranker with the specified ID does not exist | - |
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the reranker to retrieve |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully retrieved reranker | - |
| 400 | Invalid request - reranker ID in invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to view this reranker | - |
| 404 | Not found - reranker with the specified ID does not exist | - |
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
| Name | Type | Description | Notes |
|---|---|---|---|
| owner_id | 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 | str | Filter rerankers by provider type (e.g., OPENAI, TEI, VLLM, etc.) | [optional] |
| label_ | str | Filter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=search) | [optional] |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully retrieved rerankers | - |
| 400 | Invalid request - invalid filter parameters or pagination token | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to list rerankers | - |
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
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the reranker to update | |
| update_reranker_request | UpdateRerankerRequest | Updated reranker configuration details |
Return type
Authorization
HTTP request headers
- Content-Type: application/json
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully updated reranker | - |
| 400 | Invalid request - invalid fields or label strategy conflict | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to update this reranker | - |
| 404 | Not found - reranker with the specified ID does not exist | - |
| 409 | Conflict - update would create duplicate with same endpoint_url, api_path, and model_identifier | - |