Embedders API
Embedders API documentation for Python SDK
All URIs are relative to http://localhost:8080
| Method | HTTP request | Description |
|---|---|---|
| create_embedder | POST /v1/embedders | Create a new embedder |
| delete_embedder | DELETE /v1/embedders/{id} | Delete an embedder |
| get_embedder | GET /v1/embedders/{id} | Get an embedder by ID |
| list_embedders | GET /v1/embedders | List embedders |
| update_embedder | PUT /v1/embedders/{id} | Update an embedder |
create_embedder
EmbedderResponse create_embedder(embedder_creation_request)
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 ALREADY_EXISTS if another embedder exists with identical {owner_id, provider_type, endpoint_url, api_path, model_identifier, credentials_fingerprint} 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 api_path field defaults to '/embeddings' if omitted. Requires CREATE_EMBEDDER_OWN permission (or CREATE_EMBEDDER_ANY for admin users).
Example
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.embedder_creation_request import EmbedderCreationRequest
from goodmem_client.models.embedder_response import EmbedderResponse
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.EmbeddersApi(api_client)
embedder_creation_request = {"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"}} # EmbedderCreationRequest | Embedder configuration details
try:
# Create a new embedder
api_response = api_instance.create_embedder(embedder_creation_request)
print("The response of EmbeddersApi->create_embedder:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling EmbeddersApi->create_embedder: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| embedder_creation_request | EmbedderCreationRequest | Embedder configuration details |
Return type
Authorization
HTTP request headers
- Content-Type: application/json
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 201 | Successfully created embedder | * Location - URL of the created embedder resource |
| 400 | Invalid request - missing required fields or invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to create embedders | - |
| 409 | Conflict - embedder already exists with identical owner_id, provider_type, endpoint_url, api_path, model_identifier, and credentials_fingerprint | - |
delete_embedder
delete_embedder(id)
Delete an embedder
Permanently deletes an embedder configuration. This operation cannot be undone and removes the embedder record and securely deletes stored credentials. IMPORTANT: This does NOT invalidate or delete embeddings previously created with this embedder - existing embeddings remain accessible. Requires DELETE_EMBEDDER_OWN permission for embedders you own (or DELETE_EMBEDDER_ANY for admin users).
Example
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.EmbeddersApi(api_client)
id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the embedder to delete
try:
# Delete an embedder
api_instance.delete_embedder(id)
except Exception as e:
print("Exception when calling EmbeddersApi->delete_embedder: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the embedder to delete |
Return type
void (empty response body)
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: Not defined
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 204 | Embedder successfully deleted | - |
| 400 | Invalid request - embedder ID in invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to delete this embedder | - |
| 404 | Not found - embedder with the specified ID does not exist | - |
get_embedder
EmbedderResponse get_embedder(id)
Get an embedder by ID
Retrieves the details of a specific embedder configuration by its unique identifier. Requires READ_EMBEDDER_OWN permission for embedders you own (or READ_EMBEDDER_ANY for admin users to view any user's embedders). This is a read-only operation with no side effects.
Example
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.embedder_response import EmbedderResponse
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.EmbeddersApi(api_client)
id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the embedder to retrieve
try:
# Get an embedder by ID
api_response = api_instance.get_embedder(id)
print("The response of EmbeddersApi->get_embedder:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling EmbeddersApi->get_embedder: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the embedder to retrieve |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully retrieved embedder | - |
| 400 | Invalid request - embedder ID in invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to view this embedder | - |
| 404 | Not found - embedder with the specified ID does not exist | - |
list_embedders
ListEmbeddersResponse list_embedders(owner_id=owner_id, provider_type=provider_type, label_=label_)
List embedders
Retrieves a list of embedder configurations accessible to the caller, with optional filtering. PERMISSION-BASED FILTERING: With LIST_EMBEDDER_OWN permission, you can only see your own embedders (owner_id filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any owner_id. This is a read-only operation with no side effects.
Example
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.list_embedders_response import ListEmbeddersResponse
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.EmbeddersApi(api_client)
owner_id = '550e8400-e29b-41d4-a716-446655440000' # str | Filter embedders by owner ID. With LIST_EMBEDDER_ANY permission, omitting this shows all accessible embedders; providing it filters by that owner. With LIST_EMBEDDER_OWN permission, only your own embedders are shown regardless of this parameter. (optional)
provider_type = 'OPENAI' # str | Filter embedders by provider type (e.g., OPENAI, OPENAI_COMPATIBLE, COHERE, etc.) (optional)
label_ = '?label.environment=production&label.team=nlp' # str | Filter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=nlp) (optional)
try:
# List embedders
api_response = api_instance.list_embedders(owner_id=owner_id, provider_type=provider_type, label_=label_)
print("The response of EmbeddersApi->list_embedders:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling EmbeddersApi->list_embedders: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| owner_id | str | Filter embedders by owner ID. With LIST_EMBEDDER_ANY permission, omitting this shows all accessible embedders; providing it filters by that owner. With LIST_EMBEDDER_OWN permission, only your own embedders are shown regardless of this parameter. | [optional] |
| provider_type | str | Filter embedders by provider type (e.g., OPENAI, OPENAI_COMPATIBLE, COHERE, etc.) | [optional] |
| label_ | str | Filter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=nlp) | [optional] |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully retrieved embedders | - |
| 400 | Invalid request - invalid filter parameters or pagination token | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to list embedders | - |
update_embedder
EmbedderResponse update_embedder(id, update_embedder_request)
Update an embedder
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. IMPORTANT: provider_type is IMMUTABLE after creation and cannot be changed. CRITICAL: Returns FAILED_PRECONDITION if attempting to update core fields (dimensionality, distribution_type, model_identifier) while the embedder is actively referenced by spaces or ingestion jobs. Requires UPDATE_EMBEDDER_OWN permission for embedders you own (or UPDATE_EMBEDDER_ANY for admin users).
Example
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.embedder_response import EmbedderResponse
from goodmem_client.models.update_embedder_request import UpdateEmbedderRequest
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.EmbeddersApi(api_client)
id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the embedder to update
update_embedder_request = {"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","maxSequenceLength":"8192","supportedModalities":["TEXT"],"credentials":"{\\\"kind\\\":\\\"CREDENTIAL_KIND_API_KEY\\\",\\\"apiKey\\\":{\\\"inlineSecret\\\":\\\"sk-updated-api-key-here\\\"}}","version":"2.0.1","monitoringEndpoint":"https://monitoring.company.com/embedders/status","replaceLabels":{"environment":"production","team":"ml-platform","cost-center":"ai-infrastructure"}} # UpdateEmbedderRequest | Embedder update details
try:
# Update an embedder
api_response = api_instance.update_embedder(id, update_embedder_request)
print("The response of EmbeddersApi->update_embedder:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling EmbeddersApi->update_embedder: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the embedder to update | |
| update_embedder_request | UpdateEmbedderRequest | Embedder update details |
Return type
Authorization
HTTP request headers
- Content-Type: application/json
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully updated embedder | - |
| 400 | Invalid request - ID format or update parameters invalid | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to update this embedder | - |
| 404 | Not found - embedder with the specified ID does not exist | - |
| 412 | Precondition failed - cannot update core fields while embedder is actively referenced by spaces or ingestion jobs | - |