Ping

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

Class — ai.pairsys.goodmem.client.api.PingAPI (extends internal PingAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

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

Async variants

Every method listed below also exists on ai.pairsys.goodmem.client.api.AsyncPingAPI (accessed via asyncClient.ping on an AsyncGoodmem) with the same parameter list, wrapped in CompletableFuture<T>. Paginated list methods return CompletableFuture<AsyncPage<T>>; streaming methods return CompletableFuture<PingStream>. 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.ping.<method>(...)  // returns CompletableFuture<T>
}

Method Summary

Method Detail

once(PingOnceRequest)

PingResult once(PingOnceRequest request)

Javadoc — once(PingOnceRequest)

Runs a single ping probe and returns the probe result. Requires both the target-specific PING operation and its corresponding EXECUTE operation: PING_EMBEDDER plus EXECUTE_EMBEDDER, PING_RERANKER plus EXECUTE_RERANKER, or PING_LLM plus EXECUTE_LLM.

HTTP — POST /v1/ping:once

Parameters

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

Returns — PingResult

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.

Example

PingResult pingResult = client.ping.once(PingOnceRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/ping:once' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "targetId": "your-embedder-id"
  }'

stream(PingStreamRequest)

PingStream stream(PingStreamRequest request)

Javadoc — stream(PingStreamRequest)

Opens a streaming ping session and returns per-probe results plus a terminal summary. Requires both the target-specific PING operation and its corresponding EXECUTE operation: PING_EMBEDDER plus EXECUTE_EMBEDDER, PING_RERANKER plus EXECUTE_RERANKER, or PING_LLM plus EXECUTE_LLM.

HTTP — POST /v1/ping:stream

Parameters

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

Returns — PingStream

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.

Example

PingStream pingStream = client.ping.stream(PingStreamRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/ping:stream' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "targetId": "your-embedder-id",
    "count": 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.