Update an embedder

PUT /v1/embedders/{id}: Updates an existing embedder configuration including display information, endpoint configuration, model parameters, credentials, and labels.

Updates an existing embedder configuration including display information, endpoint configuration, model parameters, credentials, and labels. All fields are optional - only specified fields will be updated. Omitting apiPath preserves the existing path; setting it blank resets it to '/v2/embed' for Cohere, '/v1/embeddings' for Jina, '/embed' for TEI, or '/embeddings' for other providers.

IMPORTANT: providerType is IMMUTABLE after creation and cannot be changed.

CRITICAL: Returns HTTP 412 Precondition Failed (FAILED_PRECONDITION) if attempting to update core fields (dimensionality, distributionType, modelIdentifier) while the embedder is actively referenced by spaces or ingestion jobs.

DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if the update would create a duplicate embedder with the same provider, endpoint, model, dimensionality, distribution, and credentials for this owner. Requires UPDATE_EMBEDDER on the requested embedder.

Authorization

x-api-key<token>

In: header

Path Parameters

idstring

The unique identifier of the embedder to update

Request Body

Embedder update details

displayName?string | null

User-facing name of the embedder

Example"Updated OpenAI Embedder"

Length1 <= length <= 255

description?string | null

Description of the embedder

Example"Updated description for OpenAI's text embedding model"

endpointUrl?string | null

API endpoint URL

Example"https://api.openai.com/v1"

apiPath?string | null

API path for embeddings requests. Omit to keep the existing path; set blank to reset to the provider default (Cohere /v2/embed, Jina /v1/embeddings, TEI /embed, others /embeddings).

Example"/embeddings"

modelIdentifier?string | null

Model identifier

Example"text-embedding-3-small"

dimensionality?integer | null

Output vector dimensions

Example1536

Formatint32

Range1 <= value

distributionType?DistributionType | null

Type of embedding distribution (DENSE or SPARSE)

Example"DENSE"

maxSequenceLength?integer | null

Maximum input sequence length

Example8192

Formatint32

Range1 <= value

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

Replace stored credentials. Omit this field to preserve the current credentials; a present empty payload is invalid and never clears them.

Example{"kind":"CREDENTIAL_KIND_API_KEY","apiKey":{"inlineSecret":"sk-rotated-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

apiKeyApiKeyAuth

Configuration when kind is CREDENTIAL_KIND_API_KEY

Example

{"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

gcpAdcGcpAdcAuth

Configuration when kind is CREDENTIAL_KIND_GCP_ADC

Example{"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

replaceLabels?object | null

Replace all existing labels with these (mutually exclusive with mergeLabels)

Example{"environment":"production","team":"nlp"}

Propertiesproperties <= 20

Empty Object

mergeLabels?object | null

Merge these labels with existing ones (mutually exclusive with replaceLabels)

Example{"environment":"production","team":"nlp"}

Propertiesproperties <= 20

Empty Object

version?string | null

Version information

Example"1.0.0"

monitoringEndpoint?string | null

Monitoring endpoint URL

Example"https://monitoring.example.com/embedders/status"

Response Body

curl -X PUT "https://your-goodmem-server.example.com/v1/embedders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Updated Production Embedder",
    "description": "Updated OpenAI embedding model with enhanced configuration for production use",
    "endpointUrl": "https://api.openai.com/v1",
    "apiPath": "/embeddings",
    "modelIdentifier": "text-embedding-3-large",
    "dimensionality": 3072,
    "distributionType": "DENSE",
    "maxSequenceLength": 8192,
    "credentials": {
      "apiKey": {
        "inlineSecret": "sk-updated-api-key-here",
        "secretRef": {
          "uri": "vault://path/to/secret"
        },
        "headerName": "Authorization",
        "prefix": "Bearer "
      },
      "kind": "CREDENTIAL_KIND_API_KEY"
    },
    "replaceLabels": {
      "environment": "production",
      "team": "ml-platform",
      "cost-center": "ai-infrastructure"
    },
    "mergeLabels": {
      "environment": "production",
      "team": "nlp"
    },
    "version": "2.0.1",
    "monitoringEndpoint": "https://monitoring.company.com/embedders/status"
  }'

curl -X PUT "https://your-goodmem-server.example.com/v1/embedders/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{    "displayName": "Updated Production Embedder",    "description": "Updated OpenAI embedding model with enhanced configuration for production use",    "endpointUrl": "https://api.openai.com/v1",    "apiPath": "/embeddings",    "modelIdentifier": "text-embedding-3-large",    "dimensionality": 3072,    "distributionType": "DENSE",    "maxSequenceLength": 8192,    "credentials": {      "apiKey": {        "inlineSecret": "sk-updated-api-key-here",        "secretRef": {          "uri": "vault://path/to/secret"        },        "headerName": "Authorization",        "prefix": "Bearer "      },      "kind": "CREDENTIAL_KIND_API_KEY"    },    "replaceLabels": {      "environment": "production",      "team": "ml-platform",      "cost-center": "ai-infrastructure"    },    "mergeLabels": {      "environment": "production",      "team": "nlp"    },    "version": "2.0.1",    "monitoringEndpoint": "https://monitoring.company.com/embedders/status"  }'

{
  "embedderId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "OpenAI Ada-2",
  "description": "OpenAI's text embedding model with 1536 dimensions",
  "providerType": "OPENAI",
  "endpointUrl": "https://api.openai.com/v1",
  "apiPath": "/embeddings",
  "modelIdentifier": "text-embedding-3-small",
  "dimensionality": 1536,
  "distributionType": "DENSE",
  "maxSequenceLength": 8192,
  "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": "nlp"
  },
  "version": "1.0.0",
  "monitoringEndpoint": "https://monitoring.example.com/embedders/status",
  "ownerId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": 1617293472000,
  "updatedAt": 1617293472000,
  "createdById": "550e8400-e29b-41d4-a716-446655440000",
  "updatedById": "550e8400-e29b-41d4-a716-446655440000"
}

Empty

Authorization

Path Parameters

Request Body

Response Body

200

400

401

403

404

409

412