Embedders

Methods on this page are called as client.embedders.<method>(...) on a Goodmem instance.

Class — ai.pairsys.goodmem.client.api.EmbeddersAPI (extends internal EmbeddersAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

try (Goodmem client = Goodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    // client.embedders.<method>(...)
}

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncEmbeddersAPI (accessed via asyncClient.embedders on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>. See the async client guide for composition patterns.

import ai.pairsys.goodmem.client.AsyncGoodmem;

try (AsyncGoodmem asyncClient = AsyncGoodmem.builder()
        .baseUrl("http://localhost:8080")
        .apiKey("gm_...")
        .build()) {
    asyncClient.embedders.<method>(...)  // returns CompletableFuture<T>
}

Method Detail

`create(EmbedderCreationRequest)`

EmbedderResponse create(EmbedderCreationRequest request)

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, dimensionality, distributionType, 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).

Convenience override: applies declarative transforms (registry lookup / endpoint inference / default injection / credential check as declared in convenience.json) before forwarding to the raw Tier-2 request. Any field already set on request wins over registry values.

HTTP — POST /v1/embedders

Parameters

request (EmbedderCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — EmbedderResponse

Example

EmbedderResponse embedderResponse = client.embedders.create(EmbedderCreationRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/embedders' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc Embedder",
    "modelIdentifier": "text-embedding-3-small",
    "labels": {
      "env": "docs"
    },
    "credentials": {
      "kind": "CREDENTIAL_KIND_API_KEY",
      "apiKey": {
        "inlineSecret": "sk-..."
      }
    },
    "providerType": "OPENAI",
    "supportedModalities": [
      "TEXT"
    ],
    "maxSequenceLength": 8192,
    "endpointUrl": "https://api.openai.com/v1",
    "dimensionality": 1536,
    "distributionType": "DENSE"
  }'

`create(EmbedderCreationRequest, String)`

EmbedderResponse create(EmbedderCreationRequest request, String apiKey)

Convenience overload: auto-fills provider / endpoint / dimensionality from the bundled model registry keyed by modelIdentifier, and converts a bare apiKey string to the structured EndpointAuthentication. Pass null for apiKey to preserve request.credentials(). Any field already set on request wins over registry values.

HTTP — POST /v1/embedders

Parameters

request (EmbedderCreationRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.
apiKey (String, optional) — bare API key for the upstream provider. Converted to EndpointAuthentication via Transforms.apiKeyToCredentials. Pass null to preserve request.credentials().

Returns — EmbedderResponse

Example

EmbedderResponse embedderResponse = client.embedders.create(EmbedderCreationRequest.builder()
            // …set required fields…
            .build(), "<provider-api-key>");

REST equivalent

curl -X POST 'http://localhost:8080/v1/embedders' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc Embedder",
    "modelIdentifier": "text-embedding-3-small",
    "labels": {
      "env": "docs"
    },
    "credentials": {
      "kind": "CREDENTIAL_KIND_API_KEY",
      "apiKey": {
        "inlineSecret": "sk-..."
      }
    },
    "providerType": "OPENAI",
    "supportedModalities": [
      "TEXT"
    ],
    "maxSequenceLength": 8192,
    "endpointUrl": "https://api.openai.com/v1",
    "dimensionality": 1536,
    "distributionType": "DENSE"
  }'

`delete(String)`

void delete(String id)

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

HTTP — DELETE /v1/embedders/{id}

Parameters

id (String) — The unique identifier of the embedder to delete

Returns — None (HTTP 204).

Example

client.embedders.delete("...");

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/embedders/{id}' \
  -H "x-api-key: gm_..."

`get(String)`

EmbedderResponse get(String 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.

HTTP — GET /v1/embedders/{id}

Parameters

id (String) — The unique identifier of the embedder to retrieve

Returns — EmbedderResponse

Example

EmbedderResponse embedderResponse = client.embedders.get("...");

REST equivalent

curl -X GET 'http://localhost:8080/v1/embedders/{id}' \
  -H "x-api-key: gm_..."

`list(EmbedderListOptions)`

List<EmbedderResponse> list(EmbedderListOptions options)

Retrieves a list of embedder configurations accessible to the caller, with optional filtering. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production). 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.

HTTP — GET /v1/embedders

Parameters

options (EmbedderListOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns — List``<EmbedderResponse>

Example

List<EmbedderResponse> list = client.embedders.list(EmbedderListOptions.builder().build());

REST equivalent

curl -X GET 'http://localhost:8080/v1/embedders' \
  -H "x-api-key: gm_..."

`update(String, UpdateEmbedderRequest)`

EmbedderResponse update(String id, UpdateEmbedderRequest request)

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

HTTP — PUT /v1/embedders/{id}

Parameters

id (String) — The unique identifier of the embedder to update
request (UpdateEmbedderRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — EmbedderResponse

Example

EmbedderResponse embedderResponse = client.embedders.update("...", UpdateEmbedderRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/embedders/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Doc Embedder (updated)",
    "mergeLabels": {
      "version": "2"
    }
  }'

Errors

Every method on this page may throw the standard HTTP-error class hierarchy rooted at GoodmemException:

BadRequestException (400), AuthenticationException (401), PermissionDeniedException (403), NotFoundException (404), ConflictException (409), UnprocessableEntityException (422), RateLimitException (429), InternalServerException (5xx), or the generic ApiException for any other 4xx/5xx. All are unchecked (RuntimeException). See Errors.

All error classes live in ai.pairsys.goodmem.client.errors and are unchecked (RuntimeException). Async siblings complete the returned CompletableFuture exceptionally with the same types, wrapped in CompletionException at await time. See Errors on the index for the full table.

Embedders

On this page