GoodMemRun a single ping probe
POST /v1/ping:once: Runs a single ping probe and returns the probe result.
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. Decision models require READ_DECISION_MODEL, PING_DECISION_MODEL, and EXECUTE_DECISION_MODEL. Probes make real provider calls and may incur charges.
ApiKeyAuthx-api-key<token>GoodMem-Timeout-Ms?integerOptional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.
int641 <= value <= 86400000Single ping probe request
application/json- body
Request payload for a single ping probe
targetId*stringTarget resource ID (UUID)
uuid"550e8400-e29b-41d4-a716-446655440000"targetTypeHint?|Optional hint for the target resource type
"EMBEDDER"payloadType?|Desired payload type (defaults to provider-specific value)
"TEXT"payload?|Explicit UTF-8 payload to send with the probe (mutually exclusive with payloadSizeBytes)
"ping"payloadSizeBytes?|Synthetic payload size in bytes (mutually exclusive with payload)
int320 <= value64timeoutMs?|Per-probe timeout in milliseconds (0 uses server default)
int320 <= value5000Ping probe result
application/json- response
Result from an individual ping probe
endpoint*Resolved endpoint metadata for the target
seq*integerSequential probe number (1-based)
int320 <= value1bytesSent*integerPayload bytes transmitted
int320 <= value64bytesReceived*integerPayload bytes received
int320 <= value64ok*booleanTrue when the provider responded successfully within the timeout
truehttpStatus*integerProvider HTTP status code or equivalent transport status
int320 <= value200errorMessage?|Human-readable error message when ok=false
"Probe exceeded timeout of 5000 ms"rttMs*numberObserved round-trip latency in milliseconds
double0 <= value123.4timing*Raw timing data recorded on the server
metadata?|Additional provider metadata (request IDs, throttling signals, etc.)
properties <= 20{ "request_id": "abc123"}curl -X POST 'https://your-goodmem-server.example.com/v1/ping:once' \ -H 'GoodMem-Timeout-Ms: 30000' \ -H 'Content-Type: application/json' \ -d '{ "targetId": "550e8400-e29b-41d4-a716-446655440000", "targetTypeHint": "EMBEDDER", "payloadType": "TEXT", "payload": "ping", "payloadSizeBytes": 64, "timeoutMs": 5000}'{ "endpoint": { "targetType": "EMBEDDER", "targetId": "550e8400-e29b-41d4-a716-446655440000", "resolvedEndpoint": "https://api.openai.com/v1/embeddings", "provider": "OPENAI", "modelIdentifier": "text-embedding-3-small" }, "seq": 1, "bytesSent": 64, "bytesReceived": 64, "ok": true, "httpStatus": 200, "errorMessage": "Probe exceeded timeout of 5000 ms", "rttMs": 123.4, "timing": { "clientSendTimeUnixNanos": 1712082300123456800, "serverReceivedTimeUnixNanos": 1712082301123456800, "serverSendTimeUnixNanos": 1712082302123456800, "clientReceiveTimeUnixNanos": 1712082303123456800 }, "metadata": { "request_id": "abc123" }}