Admin

Java SDK reference for server administration: retrieval log policies, ownership transfer, draining, license reloads, and job purging.

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

Class — ai.pairsys.goodmem.client.api.AdminAPI (extends internal AdminAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

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

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncAdminAPI (accessed via asyncClient.admin 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.admin.<method>(...)  // returns CompletableFuture<T>
}

Method Summary

Modifier and Type	Method	Description
`AdminPurgeJobsResponse`	`backgroundJobsPurge(AdminPurgeJobsRequest)`	Purge completed background jobs
`AdminDrainResponse`	`drain(AdminDrainRequest)`	Request the server to enter drain mode
`AdminReloadLicenseResponse`	`licenseReload()`	Reload the active license from disk
`RetrieveMemoryLogPolicy`	`retrieveMemoryLogPoliciesCreate(CreateRetrieveMemoryLogPolicyRequest)`	Create a RetrieveMemory log policy
`RetrieveMemoryLogPolicy`	`retrieveMemoryLogPoliciesDelete(String, DeleteRetrieveMemoryLogPolicyRequest)`	Delete a RetrieveMemory log policy
`RetrieveMemoryLogPolicy`	`retrieveMemoryLogPoliciesGet(String, Map<String, Object>)`	Get a RetrieveMemory log policy
`Page<RetrieveMemoryLogPolicy>`	`retrieveMemoryLogPoliciesList(Map<String, Object>)`	List RetrieveMemory log policies
`TransferInstanceOwnershipResponse`	`transferInstanceOwnership(TransferOwnershipRequest)`	Transfer GoodMem instance ownership

Method Detail

`backgroundJobsPurge(AdminPurgeJobsRequest)`

AdminPurgeJobsResponse backgroundJobsPurge(AdminPurgeJobsRequest request)

Deletes terminal background jobs older than a retention cutoff.

HTTP: POST /v1/admin/background-jobs:purge

Parameters:

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

Returns: AdminPurgeJobsResponse

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:

AdminAPIBase.backgroundJobsPurge(AdminPurgeJobsRequest) on javadoc.io

Example

AdminPurgeJobsResponse adminPurgeJobsResponse = client.admin.backgroundJobsPurge(AdminPurgeJobsRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/admin/background-jobs:purge' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* AdminPurgeJobsRequest fields, see Javadoc */ }'

`drain(AdminDrainRequest)`

AdminDrainResponse drain(AdminDrainRequest request)

Initiates drain mode and optionally waits for the server to quiesce.

HTTP: POST /v1/admin:drain

Parameters:

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

Returns: AdminDrainResponse

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:

AdminAPIBase.drain(AdminDrainRequest) on javadoc.io

Example

AdminDrainResponse adminDrainResponse = client.admin.drain(AdminDrainRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/admin:drain' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "timeoutSec": 0
  }'

`licenseReload()`

AdminReloadLicenseResponse licenseReload()

Triggers the server to reload its license file from the configured directory and returns metadata about the currently active license.

HTTP: POST /v1/admin/license:reload

Parameters:

(no parameters)

Returns: AdminReloadLicenseResponse

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:

AdminAPIBase.licenseReload() on javadoc.io

Example

AdminReloadLicenseResponse adminReloadLicenseResponse = client.admin.licenseReload();

REST equivalent

curl -X POST 'http://localhost:8080/v1/admin/license:reload' \
  -H "x-api-key: gm_..."

`retrieveMemoryLogPoliciesCreate(CreateRetrieveMemoryLogPolicyRequest)`

RetrieveMemoryLogPolicy retrieveMemoryLogPoliciesCreate(CreateRetrieveMemoryLogPolicyRequest request)

Creates an immutable administrative policy that can automatically enable durable RetrieveMemory request logging.

HTTP: POST /v1/admin/retrieve-memory-log-policies

Parameters:

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

Returns: RetrieveMemoryLogPolicy

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:

AdminAPIBase.retrieveMemoryLogPoliciesCreate(CreateRetrieveMemoryLogPolicyRequest) on javadoc.io

Example

RetrieveMemoryLogPolicy retrieveMemoryLogPolicy = client.admin.retrieveMemoryLogPoliciesCreate(CreateRetrieveMemoryLogPolicyRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/admin/retrieve-memory-log-policies' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* CreateRetrieveMemoryLogPolicyRequest fields, see Javadoc */ }'

`retrieveMemoryLogPoliciesDelete(String, DeleteRetrieveMemoryLogPolicyRequest)`

RetrieveMemoryLogPolicy retrieveMemoryLogPoliciesDelete(String id, DeleteRetrieveMemoryLogPolicyRequest request)

Idempotently tombstones an immutable RetrieveMemory log policy.

HTTP: DELETE /v1/admin/retrieve-memory-log-policies/{id}

Parameters:

id (String) — The UUID of the policy to delete
request (DeleteRetrieveMemoryLogPolicyRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns: RetrieveMemoryLogPolicy

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:

AdminAPIBase.retrieveMemoryLogPoliciesDelete(String, DeleteRetrieveMemoryLogPolicyRequest) on javadoc.io

Example

RetrieveMemoryLogPolicy retrieveMemoryLogPolicy = client.admin.retrieveMemoryLogPoliciesDelete("...", DeleteRetrieveMemoryLogPolicyRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X DELETE 'http://localhost:8080/v1/admin/retrieve-memory-log-policies/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* DeleteRetrieveMemoryLogPolicyRequest fields, see Javadoc */ }'

`retrieveMemoryLogPoliciesGet(String, Map<String, Object>)`

RetrieveMemoryLogPolicy retrieveMemoryLogPoliciesGet(String id, Map<String, Object> query)

Retrieves a live RetrieveMemory log policy by UUID, or a tombstoned policy when includeDeleted is true.

HTTP: GET /v1/admin/retrieve-memory-log-policies/{id}

Parameters:

id (String) — The UUID of the policy to retrieve
query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns: RetrieveMemoryLogPolicy

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:

AdminAPIBase.retrieveMemoryLogPoliciesGet(String, Map<String, Object>) on javadoc.io

Example

RetrieveMemoryLogPolicy retrieveMemoryLogPolicy = client.admin.retrieveMemoryLogPoliciesGet("...", java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/admin/retrieve-memory-log-policies/{id}' \
  -H "x-api-key: gm_..."

`retrieveMemoryLogPoliciesList(Map<String, Object>)`

Page<RetrieveMemoryLogPolicy> retrieveMemoryLogPoliciesList(Map<String, Object> query)

Lists RetrieveMemory log policies with optional tombstone, active-time, name, label, sort, and pagination filters.

LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

HTTP: GET /v1/admin/retrieve-memory-log-policies

Parameters:

query (Map<String, Object>) — query-string parameters; use Map.of() when none.

Returns: Page<RetrieveMemoryLogPolicy>

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:

AdminAPIBase.retrieveMemoryLogPoliciesList(Map<String, Object>) on javadoc.io

Example

Page<RetrieveMemoryLogPolicy> page = client.admin.retrieveMemoryLogPoliciesList(java.util.Map.of());

REST equivalent

curl -X GET 'http://localhost:8080/v1/admin/retrieve-memory-log-policies' \
  -H "x-api-key: gm_..."

`transferInstanceOwnership(TransferOwnershipRequest)`

TransferInstanceOwnershipResponse transferInstanceOwnership(TransferOwnershipRequest request)

Transfers the singleton GoodMem instance to another active human principal. Only the current instance owner may invoke this operation; ADMIN, MANAGE_ACCESS, and ordinary grants are insufficient. Ownership and the synthetic ROOT assignment move atomically. All ordinary roles, including ADMIN, remain unchanged. No credential is created or returned. After an unknown outcome, read the current owner before retrying.

HTTP: POST /v1/admin:transferInstanceOwnership

Parameters:

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

Returns: TransferInstanceOwnershipResponse

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:

AdminAPIBase.transferInstanceOwnership(TransferOwnershipRequest) on javadoc.io

Example

TransferInstanceOwnershipResponse transferInstanceOwnershipResponse = client.admin.transferInstanceOwnership(TransferOwnershipRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/admin:transferInstanceOwnership' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{ /* TransferOwnershipRequest fields, see Javadoc */ }'

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