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.

Authorization

x-api-key<token>

In: header

Request Body

Reranker configuration details

displayNamestring

User-facing name of the reranker

Default"BGE Cross-Encoder Reranker"

Length1 <= length <= 255

description?string | null

Description of the reranker

Default"BAAI BGE reranker for cross-encoder semantic ranking"

providerTypeProviderType

Type of reranking provider

Default"TEI"

endpointUrlstring

API endpoint URL

Default"http://bge.reranker.goodmem.ai:8010"

apiPath?string | null

API path for reranking request (defaults: Cohere /v2/rerank, Jina /v1/rerank, others /rerank)

Default"/rerank"

modelIdentifierstring

Model identifier

Default"BAAI/bge-reranker-base"

supportedModalities?array<Modality> | null

Supported content modalities (defaults to TEXT if not provided)

Default["TEXT"]

credentials?ApiKey (CREDENTIAL_KIND_API_KEY) | GcpAdc (CREDENTIAL_KIND_GCP_ADC) | None (omit this field)

Structured credential payload describing how to authenticate with the provider. Required for SaaS providers; optional for local deployments.

Default{"kind":"CREDENTIAL_KIND_API_KEY","apiKey":{"inlineSecret":"sk-reranker-api-key"}}

Structured credential payload describing how GoodMem should authenticate with an upstream provider.

kindstring

Credential strategy — fixed to CREDENTIAL_KIND_API_KEY for this variant

Default"CREDENTIAL_KIND_API_KEY"

apiKeyApiKeyAuth

Configuration when kind is CREDENTIAL_KIND_API_KEY

Default

{"inlineSecret":"sk-1234567890abcdef","secretRef":{"uri":"vault://path/to/secret"},"headerName":"Authorization","prefix":"Bearer "}

labels?object | null

Optional annotations to aid operators (e.g., "owner=vertex")

Propertiesproperties <= 20

Empty Object

Structured credential payload describing how GoodMem should authenticate with an upstream provider.

kindstring

Credential strategy — fixed to CREDENTIAL_KIND_GCP_ADC for this variant

Default"CREDENTIAL_KIND_GCP_ADC"

gcpAdcGcpAdcAuth

Configuration when kind is CREDENTIAL_KIND_GCP_ADC

Default{"scopes":["https://www.googleapis.com/auth/cloud-platform"],"quotaProjectId":"my-quota-project"}

labels?object | null

Optional annotations to aid operators (e.g., "owner=vertex")

Propertiesproperties <= 20

Empty Object

labels?object | null

User-defined labels for categorization

Default{"environment":"production","team":"search"}

Propertiesproperties <= 20

Empty Object

version?string | null

Version information

Default"1.0.0"

monitoringEndpoint?string | null

Monitoring endpoint URL

Default"https://monitoring.example.com/rerankers/status"

ownerId?string | null

Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_RERANKER_ANY permission if specified.

Formatuuid

rerankerId?string | null

Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.

Formatuuid

Response Body

curl -X POST "http://localhost:8080/v1/rerankers" \
  -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",
    "providerType": "TEI"
  }'

curl -X POST "http://localhost:8080/v1/rerankers" \  -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",    "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"
}

Empty

Create a new reranker

Authorization

Request Body

Response Body

201

400

401

403

409