Embedding Config — MDDB API

Embedding provider configuration management

List embedding configurations #

GET /v1/embedding-configs

List all embedding model configurations.

Authorization: BearerAuth or APIKeyAuth or none

Responses #

Status	Description	Body
200	List of embedding configurations	object (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Create embedding configuration #

POST /v1/embedding-configs

Create a new embedding model configuration. Required fields: id, name, provider, model, dimensions.

Supported providers: openai, ollama, cohere, voyage.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: EmbeddingConfig

{
  "apiKey": "sk-...",
  "apiUrl": "http://localhost:11434",
  "createdAt": 1704844800,
  "dimensions": 1536,
  "id": "openai-small",
  "isDefault": false,
  "model": "text-embedding-3-small",
  "name": "OpenAI Small",
  "provider": "openai"
}

Responses #

Status	Description	Body
201	Embedding configuration created	EmbeddingConfig (application/json)
400	Invalid request (missing required fields or invalid provider)	ErrorResponse (application/json)

Get embedding configuration #

GET /v1/embedding-configs/{id}

Retrieve a specific embedding configuration by ID.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string	Embedding configuration ID

Responses #

Status	Description	Body
200	Embedding configuration retrieved	EmbeddingConfig (application/json)
404	Configuration not found	ErrorResponse (application/json)

Update embedding configuration #

PUT /v1/embedding-configs/{id}

Update an existing embedding configuration. The ID in the path is used (body ID is ignored).

Supported providers: openai, ollama, cohere, voyage.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string	Embedding configuration ID

Request body #

Required.

Content type application/json: EmbeddingConfig

{
  "apiKey": "sk-...",
  "apiUrl": "http://localhost:11434",
  "createdAt": 1704844800,
  "dimensions": 1536,
  "id": "openai-small",
  "isDefault": false,
  "model": "text-embedding-3-small",
  "name": "OpenAI Small",
  "provider": "openai"
}

Responses #

Status	Description	Body
200	Embedding configuration updated	EmbeddingConfig (application/json)
400	Invalid request	ErrorResponse (application/json)

Delete embedding configuration #

DELETE /v1/embedding-configs/{id}

Delete an embedding configuration. Cannot delete the default configuration.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string	Embedding configuration ID

Responses #

Status	Description	Body
204	Embedding configuration deleted
400	Cannot delete default config	ErrorResponse (application/json)
404	Configuration not found	ErrorResponse (application/json)

Set default embedding configuration #

POST /v1/embedding-configs/set-default

Set an embedding configuration as the default. This will unset any previously default configuration and reinitialize the embedding system with the new default config.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
id (required)	string	ID of the embedding configuration to set as default

{
  "id": "openai-small"
}

Responses #

Status	Description	Body
200	Default configuration updated	object (application/json)
400	Invalid request	ErrorResponse (application/json)
404	Configuration not found	ErrorResponse (application/json)