GoodMem
ReferenceClient SDKsJava SDK

Embedders API

Embedders API documentation for Java SDK

The default url is https://localhost:8080

MethodHTTP requestDescription
createEmbedderPOST /v1/embeddersCreate a new embedder
deleteEmbedderDELETE /v1/embedders/{id}Delete an embedder
getEmbedderGET /v1/embedders/{id}Get an embedder by ID
listEmbeddersGET /v1/embeddersList embedders
updateEmbedderPUT /v1/embedders/{id}Update an embedder

createEmbedder

EmbedderResponse createEmbedder(embedderCreationRequest)

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

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.EmbeddersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    EmbeddersApi apiInstance = new EmbeddersApi(defaultClient);
    EmbedderCreationRequest embedderCreationRequest = new EmbedderCreationRequest(); // EmbedderCreationRequest | Embedder configuration details
    try {
      EmbedderResponse result = apiInstance.createEmbedder(embedderCreationRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling EmbeddersApi#createEmbedder");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
embedderCreationRequestEmbedderCreationRequestEmbedder 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 ownerId, providerType, endpointUrl, apiPath, modelIdentifier, and credentialsFingerprint-

deleteEmbedder

deleteEmbedder(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. CONFLICT: Returns HTTP 409 Conflict if the embedder is still referenced by a space. Requires DELETE_EMBEDDER_OWN permission for embedders you own (or DELETE_EMBEDDER_ANY for admin users).

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.EmbeddersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    EmbeddersApi apiInstance = new EmbeddersApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the embedder to delete
    try {
      apiInstance.deleteEmbedder(id);
    } catch (ApiException e) {
      System.err.println("Exception when calling EmbeddersApi#deleteEmbedder");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the embedder to delete

Return type

null (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-
409Conflict - embedder is still referenced by at least one space-

getEmbedder

EmbedderResponse getEmbedder(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

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.EmbeddersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    EmbeddersApi apiInstance = new EmbeddersApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the embedder to retrieve
    try {
      EmbedderResponse result = apiInstance.getEmbedder(id);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling EmbeddersApi#getEmbedder");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe 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-

listEmbedders

ListEmbeddersResponse listEmbedders(ownerId, providerType, labelStar)

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 (ownerId filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any ownerId. This is a read-only operation with no side effects.

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.EmbeddersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    EmbeddersApi apiInstance = new EmbeddersApi(defaultClient);
    String ownerId = "550e8400-e29b-41d4-a716-446655440000"; // String | 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.
    String providerType = "OPENAI"; // String | Filter embedders by provider type (e.g., OPENAI, OPENAI_COMPATIBLE, COHERE, etc.)
    String labelStar = "?label.environment=production&label.team=nlp"; // String | Filter by label value. Multiple label filters can be specified (e.g., ?label.environment=production&label.team=nlp)
    try {
      ListEmbeddersResponse result = apiInstance.listEmbedders(ownerId, providerType, labelStar);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling EmbeddersApi#listEmbedders");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
ownerIdStringFilter 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]
providerTypeStringFilter embedders by provider type (e.g., OPENAI, OPENAI_COMPATIBLE, COHERE, etc.)[optional]
labelStarStringFilter 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-

updateEmbedder

EmbedderResponse updateEmbedder(id, updateEmbedderRequest)

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: providerType is IMMUTABLE after creation and cannot be changed. CRITICAL: Returns HTTP 412 Precondition Failed (FAILED_PRECONDITION) if attempting to update core fields (dimensionality, distributionType, modelIdentifier) while the embedder is actively referenced by spaces or ingestion jobs. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if the update would create a duplicate embedder with the same provider, endpoint, model, dimensionality, distribution, and credentials for this owner. Requires UPDATE_EMBEDDER_OWN permission for embedders you own (or UPDATE_EMBEDDER_ANY for admin users).

Example

// Import classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.EmbeddersApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    EmbeddersApi apiInstance = new EmbeddersApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the embedder to update
    UpdateEmbedderRequest updateEmbedderRequest = new UpdateEmbedderRequest(); // UpdateEmbedderRequest | Embedder update details
    try {
      EmbedderResponse result = apiInstance.updateEmbedder(id, updateEmbedderRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling EmbeddersApi#updateEmbedder");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the embedder to update
updateEmbedderRequestUpdateEmbedderRequestEmbedder 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-
409Conflict - update would create a duplicate embedder for this owner-
412Precondition Failed - cannot update core fields while embedder is actively referenced by spaces or ingestion jobs-

API Keys API

API Keys API documentation for Java SDK

LLMs API

LLMs API documentation for Java SDK

On this page

createEmbedderExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsdeleteEmbedderExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsgetEmbedderExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailslistEmbeddersExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsupdateEmbedderExampleParametersReturn typeAuthorizationHTTP request headersHTTP response details