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, 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).
In: header
Embedder configuration details
User-facing name of the embedder
1 <= length <= 255Description of the embedder
Type of embedding provider
"OPENAI" | "VLLM" | "TEI" | "LLAMA_CPP" | "VOYAGE" | "COHERE" | "JINA"API endpoint URL
API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)
Model identifier
Output vector dimensions
int32Type of embedding distribution (DENSE or SPARSE)
"DENSE" | "SPARSE"Maximum input sequence length
int32Supported content modalities (defaults to TEXT if not provided)
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.
User-defined labels for categorization
properties <= 20Empty Object
Version information
Monitoring endpoint URL
Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_EMBEDDER_ANY permission if specified.
Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
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", "providerType": "OPENAI", "endpointUrl": "https://api.openai.com/v1", "apiPath": "/embeddings", "modelIdentifier": "text-embedding-3-small", "dimensionality": "1536", "distributionType": "DENSE", "maxSequenceLength": "8192", "supportedModalities": [ "TEXT" ], "credentials": { "kind": "CREDENTIAL_KIND_API_KEY", "apiKey": { "inlineSecret": "sk-your-api-key-here" } }, "labels": { "environment": "production", "team": "nlp" } }'{
"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"
],
"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"
}