Embedders

Java SDK reference for embedder configurations: creation, lookup, listing, updates, and deletion.

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 Summary

Modifier and Type	Method	Description
`EmbedderResponse`	`create(EmbedderCreationRequest)`	Create a new embedder
`EmbedderResponse`	`create(EmbedderCreationRequest, String)`	Create a new embedder
`void`	`delete(String)`	Delete an embedder
`EmbedderResponse`	`get(String, EmbedderGetOptions)`	Get an embedder by ID
`List<EmbedderResponse>`	`list(EmbedderListOptions)`	List embedders
`EmbedderResponse`	`update(String, UpdateEmbedderRequest)`	Update an embedder

Method Detail

`create(EmbedderCreationRequest)`

EmbedderResponse create(EmbedderCreationRequest request)

Creates an embedder configuration for use with memory spaces. If ownerId is omitted, the authenticated principal becomes the owner; CREATE_EMBEDDER is evaluated against that proposed embedder and owner. Returns 409 when an equivalent embedder configuration already exists for the owner. See the embedder provider guide for provider-specific configuration.

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

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.
IllegalArgumentException — thrown synchronously by the declarative pre-flight transforms (e.g. credential_check) before the HTTP request is scheduled.

See Also:

EmbeddersAPIBase.create(EmbedderCreationRequest) on javadoc.io

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

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.
IllegalArgumentException — thrown synchronously by the declarative pre-flight transforms (e.g. credential_check) before the HTTP request is scheduled.

See Also:

EmbeddersAPIBase.create(EmbedderCreationRequest, String) on javadoc.io

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 on the requested embedder.

HTTP: DELETE /v1/embedders/{id}

Parameters:

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

Returns: None (HTTP 204).

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

EmbeddersAPIBase.delete(String) on javadoc.io

Example

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

REST equivalent

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

`get(String, EmbedderGetOptions)`

EmbedderResponse get(String id, EmbedderGetOptions options)

Retrieves the details of a specific embedder configuration by its unique identifier. Requires READ_EMBEDDER on the requested embedder. The service distinguishes a missing embedder from an existing embedder the caller cannot read. 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
options (EmbedderGetOptions, optional) — typed query parameters; pass null for an empty filter set. The linked Javadoc lists every field.

Returns: EmbedderResponse

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

EmbeddersAPIBase.get(String, EmbedderGetOptions) on javadoc.io

Example

EmbedderResponse embedderResponse = client.embedders.get("...", EmbedderGetOptions.builder().build());

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

AUTHORIZATION: Requires LIST_EMBEDDER on the GoodMem instance. Each returned embedder must also be visible through READ_EMBEDDER; unauthorized embedders are filtered in PostgreSQL. The ownerId parameter filters that already-authorized result set and does not grant additional visibility. 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>

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

EmbeddersAPIBase.list(EmbedderListOptions) on javadoc.io

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 explicitly supplied embedder fields; at least one mutable field is required. Field omission and reset semantics are defined by the request schema, and providerType cannot be changed. Returns 409 if the resulting configuration duplicates another embedder for the owner, and 412 when model-defining fields are changed while the embedder is in use. Requires UPDATE_EMBEDDER on the requested embedder. See the embedder provider guide for provider-specific configuration.

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

Throws:

GoodmemException — base type for every SDK error. A concrete HTTP-status subclass (ApiException, NotFoundException, BadRequestException, …) is thrown per response code. All unchecked (RuntimeException). See Errors.

See Also:

EmbeddersAPIBase.update(String, UpdateEmbedderRequest) on javadoc.io

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.

On this page