GoodMemGoodMem
ReferenceAPIREST APIEmbedders

Create a new embedder

POST /v1/embedders: Creates an embedder configuration for use with memory spaces.

POST
/v1/embedders

Creates an embedder configuration for use with memory spaces. If ownerId is omitted, the authenticated principal becomes the owner; CREATE_EMBEDDER is evaluated against that proposed embedder and owner. Returns 409 when an equivalent embedder configuration already exists for the owner. See the embedder provider guide for provider-specific configuration.

Authorization

ApiKeyAuth
headerx-api-key<token>

Header Parameters

GoodMem-Timeout-Ms?integer

Optional 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.

Formatint64
Range1 <= value <= 86400000

Request Body

Embedder configuration details

application/json
  1. body

Request body for creating a new Embedder. An Embedder represents a configuration for vectorizing content.

displayName*string

User-facing name of the embedder

Length1 <= length <= 255
Example"OpenAI Ada-2"
description?|

Description of the embedder

Example"OpenAI's text embedding model with 1536 dimensions"
providerType*ProviderType

Type of embedding provider

Example"OPENAI"
Value in"OPENAI""VLLM""TEI""LLAMA_CPP""VOYAGE""COHERE""JINA""DASHSCOPE""GEMINI"
endpointUrl*string

Base HTTP(S) endpoint for provider requests. Gemini endpoint URLs must not contain query parameters.

Example"https://api.openai.com/v1"
apiPath?|

Provider-relative request path. Omit or send blank to use the provider default. For Gemini, this is an API version: /v1beta for Developer and /v1 for Google Cloud.

Example"/embeddings"
modelIdentifier*string

Model identifier

Example"text-embedding-3-small"
dimensionality*integer

Output vector dimensions

Formatint32
Range1 <= value
Example1536
distributionType*DistributionType

Type of embedding distribution (DENSE or SPARSE)

Example"DENSE"
Value in"DENSE""SPARSE"
maxSequenceLength?|

Maximum input sequence length

Formatint32
Range1 <= value
Example8192
supportedModalities?array<>|

Supported content modalities (defaults to TEXT if not provided)

Default
[  "TEXT"]
credentials?||

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

Example
{  "kind": "CREDENTIAL_KIND_API_KEY",  "apiKey": {    "inlineSecret": "sk-example-api-key"  }}
labels?|

User-defined labels for categorization

Propertiesproperties <= 20
Example
{  "environment": "production",  "team": "nlp"}
version?|

Version information

Example"1.0.0"
monitoringEndpoint?|

Monitoring endpoint URL

Example"https://monitoring.example.com/embedders/status"
ownerId?|

Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_EMBEDDER is evaluated against the proposed embedder and owner.

Formatuuid
Example"550e8400-e29b-41d4-a716-446655440000"
embedderId?|

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
Example"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 text default.

Example"EMBEDDING_NATIVE_TEXT"
Value in"EMBEDDING_NATIVE_TEXT""EMBEDDING_NATIVE_CONTENTS""OPENAI_COMPATIBLE"
geminiEndpointConfig?|

Gemini backend routing. Valid only for the GEMINI provider. Omit to use the Developer API; when present, backend is required and the gRPC service validates the backend-specific projectId and location contract.

Example
{  "backend": "GOOGLE_CLOUD",  "projectId": "goodmem-production",  "location": "us-central1"}

Response Body

Successfully created embedder

application/json
  1. response

Embedder configuration information

embedderId*string

Unique identifier of the embedder

Formatuuid
Example"550e8400-e29b-41d4-a716-446655440000"
displayName*string

User-facing name of the embedder

Example"OpenAI Ada-2"
description?|

Description of the embedder

Example"OpenAI's text embedding model with 1536 dimensions"
providerType*ProviderType

Type of embedding provider

Example"OPENAI"
Value in"OPENAI""VLLM""TEI""LLAMA_CPP""VOYAGE""COHERE""JINA""DASHSCOPE""GEMINI"
endpointUrl*string

Canonical base HTTP(S) endpoint used for provider requests.

Example"https://api.openai.com/v1"
apiPath?|

Configured provider-relative request path. For Gemini, this is the selected API version: /v1beta for Developer or /v1 for Google Cloud.

Example"/embeddings"
modelIdentifier*string

Model identifier

Example"text-embedding-3-small"
dimensionality*integer

Output vector dimensions

Formatint32
Range1 <= value
Example1536
distributionType*DistributionType

Type of embedding distribution (DENSE or SPARSE)

Example"DENSE"
Value in"DENSE""SPARSE"
maxSequenceLength?|

Maximum input sequence length

Formatint32
Range1 <= value
Example8192
supportedModalities*array<>

Supported content modalities

credentials?||

Stored credentials; present only when GetEmbedder explicitly requests them and the caller has READ_EMBEDDER_CREDENTIALS. Always omitted from create, update, and list responses.

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

Example
{  "environment": "production",  "team": "nlp"}
version?|

Version information

Example"1.0.0"
monitoringEndpoint?|

Monitoring endpoint URL

Example"https://monitoring.example.com/embedders/status"
ownerId*string

Owner ID of the embedder

Formatuuid
Example"550e8400-e29b-41d4-a716-446655440000"
createdAt*integer

Creation timestamp (milliseconds since epoch)

Formatint64
Example1617293472000
updatedAt*integer

Last update timestamp (milliseconds since epoch)

Formatint64
Example1617293472000
createdById*string

ID of the user who created the embedder

Formatuuid
Example"550e8400-e29b-41d4-a716-446655440000"
updatedById*string

ID of the user who last updated the embedder

Formatuuid
Example"550e8400-e29b-41d4-a716-446655440000"
dashscopeApiDialect?|

Configured DashScope request and response API dialect; present only for DashScope configurations with a persisted dialect.

Example"EMBEDDING_NATIVE_TEXT"
Value in"EMBEDDING_NATIVE_TEXT""EMBEDDING_NATIVE_CONTENTS""OPENAI_COMPATIBLE"
geminiEndpointConfig?|

Persisted Gemini backend routing; present only for Gemini embedder resources.

Example
{  "backend": "DEVELOPER",  "projectId": "goodmem-production",  "location": "us-central1"}
Example Request
curl -X POST 'https://your-goodmem-server.example.com/v1/embedders' \  -H 'GoodMem-Timeout-Ms: 30000' \  -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",  "dashscopeApiDialect": "EMBEDDING_NATIVE_TEXT",  "geminiEndpointConfig": {    "projectId": "goodmem-production",    "location": "us-central1"  },  "providerType": "OPENAI",  "distributionType": "DENSE"}'
Example Response
{  "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",  "dashscopeApiDialect": "EMBEDDING_NATIVE_TEXT",  "geminiEndpointConfig": {    "backend": "DEVELOPER",    "projectId": "goodmem-production",    "location": "us-central1"  }}

Embedders

Browse REST endpoints for creating, reading, listing, updating, and deleting embedder configurations used for memory vectorization.

Delete an embedder

DELETE /v1/embedders/{id}: Permanently deletes an embedder configuration.