Spaces

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

Class — ai.pairsys.goodmem.client.api.SpacesAPI (extends internal SpacesAPIBase).

import ai.pairsys.goodmem.client.Goodmem;

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

Async variants

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

Method Detail

`create(SpaceCreationRequest)`

Space create(SpaceCreationRequest request)

Creates a new space with the provided name, labels, and embedder configuration. A space is a container for organizing related memories. OWNER DEFAULTS: Owner defaults to authenticated user unless ownerId is provided (requires CREATE_SPACE_ANY if differs). EMBEDDER REQUIREMENTS: At least one embedder configuration must be specified. DUPLICATE DETECTION: Returns ALREADY_EXISTS if another space exists with identical {ownerId, name} (case-sensitive). Requires CREATE_SPACE_OWN permission (or CREATE_SPACE_ANY for admin users). This operation is NOT idempotent.

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/spaces

Parameters

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

Returns — Space

Example

Space space = client.spaces.create(SpaceCreationRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X POST 'http://localhost:8080/v1/spaces' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Doc Space",
    "spaceEmbedders": [
      {
        "embedderId": "your-embedder-id",
        "defaultRetrievalWeight": 1.0
      }
    ],
    "labels": {
      "env": "docs"
    },
    "defaultChunkingConfig": {
      "recursive": {
        "chunkSize": 512,
        "chunkOverlap": 64,
        "keepStrategy": "KEEP_END",
        "lengthMeasurement": "CHARACTER_COUNT"
      }
    }
  }'

`delete(String)`

void delete(String id)

Permanently deletes a space and all associated content. This operation cannot be undone. CASCADE DELETION: Removes the space record and cascades deletion to associated memories, chunks, and embedder associations. Requires DELETE_SPACE_OWN permission for spaces you own (or DELETE_SPACE_ANY for admin users). This operation is safe to retry - may return NOT_FOUND if already deleted.

HTTP — DELETE /v1/spaces/{id}

Parameters

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

Returns — None (HTTP 204).

Example

client.spaces.delete("...");

REST equivalent

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

`get(String)`

Space get(String id)

Retrieves a specific space by its unique identifier. Returns the complete space information, including name, labels, embedder configuration, and metadata. PUBLIC SPACE ACCESS: When public_read=true, any authenticated user can retrieve the space metadata, bypassing ownership checks. Otherwise, requires ownership or DISPLAY_SPACE_ANY permission. Requires DISPLAY_SPACE_OWN permission for owned spaces (or DISPLAY_SPACE_ANY for admin users to view any space). This is a read-only operation safe to retry.

HTTP — GET /v1/spaces/{id}

Parameters

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

Returns — Space

Example

Space space = client.spaces.get("...");

REST equivalent

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

`list(SpaceListOptions)`

Page<Space> list(SpaceListOptions options)

List spaces accessible to the caller, with optional filtering by owner, labels, and name. Results are paginated; pass the response's nextToken back as a query parameter to fetch subsequent pages.

HTTP — GET /v1/spaces

Parameters

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

Returns — Page<Space>

Example

Page<Space> page = client.spaces.list(SpaceListOptions.builder().build());

REST equivalent

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

`update(String, UpdateSpaceRequest)`

Space update(String id, UpdateSpaceRequest request)

Updates an existing space with new values for the specified fields. Only name, publicRead, and labels can be updated. Fields not included in the request remain unchanged. IMMUTABLE FIELDS: space_embedders, default_chunking_config, and ownerId cannot be modified after creation. NAME UNIQUENESS: Name must be unique per owner - returns ALREADY_EXISTS if name conflicts with existing space. Requires UPDATE_SPACE_OWN permission for spaces you own (or UPDATE_SPACE_ANY for admin users). This operation is idempotent.

HTTP — PUT /v1/spaces/{id}

Parameters

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

Returns — Space

Example

Space space = client.spaces.update("...", UpdateSpaceRequest.builder()
            // …set required fields…
            .build());

REST equivalent

curl -X PUT 'http://localhost:8080/v1/spaces/{id}' \
  -H "x-api-key: gm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Doc Space (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.

Spaces

On this page