Create a new embedder

Creates a new embedder configuration for vectorizing content. Embedders represent connections to different embedding API services (like OpenAI, vLLM, etc.) and include all the necessary configuration to use them with memory spaces.

DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another embedder exists with identical {ownerId, providerType, endpointUrl, apiPath, modelIdentifier, dimensionality, distributionType, 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. The apiPath field defaults to '/v2/embed' for Cohere, '/embed' for TEI, and '/embeddings' for other providers when omitted. Requires CREATE_EMBEDDER_OWN permission (or CREATE_EMBEDDER_ANY for admin users).

Authorization

x-api-key<token>

In: header

Request Body

Embedder configuration details

displayNamestring

User-facing name of the embedder

Example"OpenAI Ada-2"

Length1 <= length <= 255

description?string | null

Description of the embedder

Example"OpenAI's text embedding model with 1536 dimensions"

providerTypeProviderType

Type of embedding provider

Example"OPENAI"

endpointUrlstring

API endpoint URL

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

apiPath?string | null

API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)

Example"/embeddings"

modelIdentifierstring

Model identifier

Example"text-embedding-3-small"

dimensionalityinteger

Output vector dimensions

Example1536

Formatint32

distributionTypeDistributionType

Type of embedding distribution (DENSE or SPARSE)

Example"DENSE"

Value in"DENSE" | "SPARSE"

maxSequenceLength?integer | null

Maximum input sequence length

Example8192

Formatint32

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 such as COHERE, JINA, and VOYAGE; optional for local or proxy providers.

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

labels?object | null

User-defined labels for categorization

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"

ownerId?string | null

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

Example"550e8400-e29b-41d4-a716-446655440000"

Formatuuid

embedderId?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.

Example"550e8400-e29b-41d4-a716-446655440000"

Formatuuid

Response Body

curl -X POST "http://localhost:8080/v1/embedders" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "OpenAI Embedding Model",
    "description": "OpenAI text embedding model with 1536 dimensions",
    "endpointUrl": "https://api.openai.com/v1",
    "apiPath": "/embeddings",
    "modelIdentifier": "text-embedding-3-small",
    "dimensionality": 1536,
    "maxSequenceLength": 8192,
    "supportedModalities": [
      "TEXT"
    ],
    "credentials": {
      "apiKey": {
        "inlineSecret": "sk-your-api-key-here",
        "secretRef": {
          "uri": "vault://path/to/secret"
        },
        "headerName": "Authorization",
        "prefix": "Bearer "
      },
      "kind": "CREDENTIAL_KIND_API_KEY"
    },
    "labels": {
      "environment": "production",
      "team": "nlp"
    },
    "version": "1.0.0",
    "monitoringEndpoint": "https://monitoring.example.com/embedders/status",
    "ownerId": "550e8400-e29b-41d4-a716-446655440000",
    "embedderId": "550e8400-e29b-41d4-a716-446655440000",
    "providerType": "OPENAI",
    "distributionType": "DENSE"
  }'

curl -X POST "http://localhost:8080/v1/embedders" \  -H "Content-Type: application/json" \  -d '{    "displayName": "OpenAI Embedding Model",    "description": "OpenAI text embedding model with 1536 dimensions",    "endpointUrl": "https://api.openai.com/v1",    "apiPath": "/embeddings",    "modelIdentifier": "text-embedding-3-small",    "dimensionality": 1536,    "maxSequenceLength": 8192,    "supportedModalities": [      "TEXT"    ],    "credentials": {      "apiKey": {        "inlineSecret": "sk-your-api-key-here",        "secretRef": {          "uri": "vault://path/to/secret"        },        "headerName": "Authorization",        "prefix": "Bearer "      },      "kind": "CREDENTIAL_KIND_API_KEY"    },    "labels": {      "environment": "production",      "team": "nlp"    },    "version": "1.0.0",    "monitoringEndpoint": "https://monitoring.example.com/embedders/status",    "ownerId": "550e8400-e29b-41d4-a716-446655440000",    "embedderId": "550e8400-e29b-41d4-a716-446655440000",    "providerType": "OPENAI",    "distributionType": "DENSE"  }'

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

Create a new embedder

Authorization

Request Body

Response Body

201

400

401

403

409