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 Summary

Method Detail

create(SpaceCreationRequest)

Space create(SpaceCreationRequest request)

Javadoc — create(SpaceCreationRequest)

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 the authenticated principal unless ownerId is provided; CREATE_SPACE is evaluated against the proposed space and owner. EMBEDDER REQUIREMENTS: At least one embedder configuration must be specified. Every referenced embedder must exist, and the caller must have EXECUTE_EMBEDDER on each one. DUPLICATE DETECTION: Returns ALREADY_EXISTS if another space exists with identical {ownerId, name} (case-sensitive). 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

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.

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)

Javadoc — delete(String)

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 on the requested space. This operation is safe to retry and may return NOT_FOUND if the space was already deleted.

HTTP — DELETE /v1/spaces/{id}

Parameters

• id (String) — The unique identifier of the space 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.

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)

Javadoc — get(String)

Retrieves a specific space by its unique identifier. Returns the complete space information, including name, labels, embedder configuration, and metadata. Requires READ_SPACE on the requested space. The service distinguishes a missing space from an existing space the caller cannot read. 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

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

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)

Javadoc — list(SpaceListOptions)

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>

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

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

REST equivalent

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

transferOwnership(String, TransferOwnershipRequest)

TransferSpaceOwnershipResponse transferOwnership(String id, TransferOwnershipRequest request)

Javadoc — transferOwnership(String, TransferOwnershipRequest)

Transfers an existing space to another active human or service principal. The current space owner, the GoodMem instance owner, or an instance administrator may transfer it; a space-scoped administrator cannot. Only owner and update-audit fields change. Memories, embedder associations, grants, and role assignments remain unchanged. This operation is not idempotent under response semantics: after an unknown outcome, read the space before retrying.

HTTP — POST /v1/spaces/{id}:transferOwnership

Parameters

• id (String) — UUID of the existing space to transfer
• request (TransferOwnershipRequest) — full request payload. The linked Javadoc lists every field and its Builder setter.

Returns — TransferSpaceOwnershipResponse

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

TransferSpaceOwnershipResponse transferSpaceOwnershipResponse = client.spaces.transferOwnership("...", TransferOwnershipRequest.builder()
            // …set required fields…
            .build());

REST equivalent

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

update(String, UpdateSpaceRequest)

Space update(String id, UpdateSpaceRequest request)

Javadoc — update(String, UpdateSpaceRequest)

Updates an existing space with new values for the specified fields. Only name 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 an existing space. Requires UPDATE_SPACE on the requested space. 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

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

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.