GoodMemCreate a new reranker
POST /v1/rerankers: Creates a new reranker configuration for ranking search results.
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 the same effective provider connection and model configuration for this owner after endpoint canonicalization and provider-default resolution. Equivalent credentials participate in the comparison.
DEFAULTS: apiPath defaults to '/v2/rerank' for Cohere and '/rerank' for other providers if omitted; supportedModalities defaults to [TEXT] if omitted.
OWNER DEFAULTS: Owner defaults to the authenticated principal unless ownerId is provided; CREATE_RERANKER is evaluated against the proposed reranker and owner. This operation is NOT idempotent - each request creates a new reranker record.
ApiKeyAuthx-api-key<token>GoodMem-Timeout-Ms?integerOptional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.
int641 <= value <= 86400000Reranker configuration details
application/json- body
Request body for creating a new Reranker. A Reranker represents a configuration for reranking search results.
displayName*stringUser-facing name of the reranker
1 <= length <= 255"BGE Cross-Encoder Reranker"description?|Description of the reranker
"BAAI BGE reranker for cross-encoder semantic ranking"providerType*ProviderTypeType of reranking provider
"TEI""VLLM""TEI""LLAMA_CPP""VOYAGE""COHERE""JINA""DASHSCOPE"endpointUrl*stringAPI endpoint URL
"http://bge.reranker.goodmem.ai:8010"apiPath?|API path for reranking request (defaults: Cohere /v2/rerank, Jina /v1/rerank, others /rerank)
"/rerank"modelIdentifier*stringModel identifier
"BAAI/bge-reranker-base"supportedModalities?array<>|Supported content modalities (defaults to TEXT if not provided)
[ "TEXT"]credentials?||Structured credential payload describing how to authenticate with the provider. Required for SaaS providers; optional for local or proxy providers.
{ "kind": "CREDENTIAL_KIND_API_KEY", "apiKey": { "inlineSecret": "sk-reranker-api-key" }}labels?|User-defined labels for categorization
properties <= 20{ "environment": "production", "team": "search"}version?|Version information
"1.0.0"monitoringEndpoint?|Monitoring endpoint URL
"https://monitoring.example.com/rerankers/status"ownerId?|Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_RERANKER is evaluated against the proposed reranker and owner.
uuid"550e8400-e29b-41d4-a716-446655440000"rerankerId?|Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
uuid"550e8400-e29b-41d4-a716-446655440000"dashscopeApiDialect?|DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to infer the dialect from apiPath, the model catalog, or the native reranking default.
"RERANK_NATIVE_NESTED""RERANK_NATIVE_NESTED""RERANK_COMPATIBLE_FLAT"Successfully created reranker with Location header
application/json- response
Reranker configuration information
rerankerId*stringUnique identifier of the reranker
uuid"550e8400-e29b-41d4-a716-446655440000"displayName*stringUser-facing name of the reranker
"BGE Cross-Encoder Reranker"description?|Description of the reranker
"BAAI BGE reranker for cross-encoder semantic ranking"providerType*ProviderTypeType of reranking provider
"TEI""OPENAI""VLLM""TEI""LLAMA_CPP""VOYAGE""COHERE""JINA""DASHSCOPE""GEMINI"endpointUrl*stringAPI endpoint URL
"http://bge.reranker.goodmem.ai:8010"apiPath?|API path for reranking request
"/rerank"modelIdentifier*stringModel identifier
"BAAI/bge-reranker-base"supportedModalities*array<>Supported content modalities
credentials?||Stored credentials; present only when GetReranker explicitly requests them and the caller has READ_RERANKER_CREDENTIALS. Always omitted from create, update, and list responses.
{ "apiKey": { "inlineSecret": "sk-1234567890abcdef", "secretRef": { "uri": "vault://path/to/secret" }, "headerName": "Authorization", "prefix": "Bearer " }, "gcpAdc": { "scopes": [ "https://www.googleapis.com/auth/cloud-platform" ], "quotaProjectId": "my-quota-project" }}labels*User-defined labels for categorization
{ "environment": "production", "team": "search"}version?|Version information
"1.0.0"monitoringEndpoint?|Monitoring endpoint URL
"https://monitoring.example.com/rerankers/status"ownerId*stringOwner ID of the reranker
uuid"550e8400-e29b-41d4-a716-446655440000"createdAt*integerCreation timestamp (milliseconds since epoch)
int641617293472000updatedAt*integerLast update timestamp (milliseconds since epoch)
int641617293472000createdById*stringID of the user who created the reranker
uuid"550e8400-e29b-41d4-a716-446655440000"updatedById*stringID of the user who last updated the reranker
uuid"550e8400-e29b-41d4-a716-446655440000"dashscopeApiDialect?|Configured DashScope request and response API dialect; present only for DashScope configurations with a persisted dialect.
"RERANK_NATIVE_NESTED""RERANK_NATIVE_NESTED""RERANK_COMPATIBLE_FLAT"curl -X POST 'https://your-goodmem-server.example.com/v1/rerankers' \ -H 'GoodMem-Timeout-Ms: 30000' \ -H 'Content-Type: application/json' \ -d '{ "displayName": "BGE Cross-Encoder Reranker", "description": "BAAI BGE reranker for cross-encoder semantic ranking", "endpointUrl": "http://bge.reranker.goodmem.ai:8010", "apiPath": "/rerank", "modelIdentifier": "BAAI/bge-reranker-base", "supportedModalities": [ "TEXT" ], "credentials": { "apiKey": { "inlineSecret": "sk-demo-api-key", "secretRef": { "uri": "vault://path/to/secret" }, "headerName": "Authorization", "prefix": "Bearer " }, "kind": "CREDENTIAL_KIND_API_KEY" }, "labels": { "environment": "production", "team": "search" }, "version": "1.0.0", "monitoringEndpoint": "https://monitoring.example.com/rerankers/status", "ownerId": "550e8400-e29b-41d4-a716-446655440000", "rerankerId": "550e8400-e29b-41d4-a716-446655440000", "dashscopeApiDialect": "RERANK_NATIVE_NESTED", "providerType": "TEI"}'{ "rerankerId": "550e8400-e29b-41d4-a716-446655440000", "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": { "apiKey": { "inlineSecret": "sk-1234567890abcdef", "secretRef": { "uri": "vault://path/to/secret" }, "headerName": "Authorization", "prefix": "Bearer " }, "gcpAdc": { "scopes": [ "https://www.googleapis.com/auth/cloud-platform" ], "quotaProjectId": "my-quota-project" } }, "labels": { "environment": "production", "team": "search" }, "version": "1.0.0", "monitoringEndpoint": "https://monitoring.example.com/rerankers/status", "ownerId": "550e8400-e29b-41d4-a716-446655440000", "createdAt": 1617293472000, "updatedAt": 1617293472000, "createdById": "550e8400-e29b-41d4-a716-446655440000", "updatedById": "550e8400-e29b-41d4-a716-446655440000", "dashscopeApiDialect": "RERANK_NATIVE_NESTED"}