GoodMem
ReferenceClient SDKsJava SDK

Embedders API

Embedders API documentation for Java SDK

All URIs are relative to *http://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 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

// 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 owner_id, provider_type, endpoint_url, api_path, model_identifier, and credentials_fingerprint-

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

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

// 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: 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

// 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-
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