GoodMem
ReferenceClient SDKsPython SDK

Embedders API

Embedders API documentation for Python SDK

All URIs are relative to http://localhost:8080

MethodHTTP requestDescription
create_embedderPOST /v1/embeddersCreate a new embedder
delete_embedderDELETE /v1/embedders/{id}Delete an embedder
get_embedderGET /v1/embedders/{id}Get an embedder by ID
list_embeddersGET /v1/embeddersList embedders
update_embedderPUT /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

NameTypeDescriptionNotes
embedder_creation_requestEmbedderCreationRequestEmbedder configuration details

Return type

EmbedderResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
201Successfully created embedder* Location - URL of the created embedder resource
400Invalid request - missing required fields or invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to create embedders-
409Conflict - embedder already exists with identical owner_id, provider_type, endpoint_url, api_path, model_identifier, and credentials_fingerprint-

↑ Back to Python SDK

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

NameTypeDescriptionNotes
idstrThe unique identifier of the embedder to delete

Return type

void (empty response body)

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

HTTP response details

Status codeDescriptionResponse headers
204Embedder successfully deleted-
400Invalid request - embedder ID in invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to delete this embedder-
404Not found - embedder with the specified ID does not exist-

↑ Back to Python SDK

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

NameTypeDescriptionNotes
idstrThe unique identifier of the embedder to retrieve

Return type

EmbedderResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully retrieved embedder-
400Invalid request - embedder ID in invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to view this embedder-
404Not found - embedder with the specified ID does not exist-

↑ Back to Python SDK

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

NameTypeDescriptionNotes
owner_idstrFilter 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_typestrFilter embedders by provider type (e.g., OPENAI, OPENAI_COMPATIBLE, COHERE, etc.)[optional]
label_strFilter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=nlp)[optional]

Return type

ListEmbeddersResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully retrieved embedders-
400Invalid request - invalid filter parameters or pagination token-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to list embedders-

↑ Back to Python SDK

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

NameTypeDescriptionNotes
idstrThe unique identifier of the embedder to update
update_embedder_requestUpdateEmbedderRequestEmbedder update details

Return type

EmbedderResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully updated embedder-
400Invalid request - ID format or update parameters invalid-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to update this embedder-
404Not found - embedder with the specified ID does not exist-
412Precondition failed - cannot update core fields while embedder is actively referenced by spaces or ingestion jobs-

↑ Back to Python SDK