Spaces

Memory space management.

Methods on this page are called through client.spaces.

client.spaces.create

client.spaces.create(request: SpaceCreationRequest, requestOptions?: RequestOptions): Promise<SpaceResponseShape>

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.

HTTP: POST /v1/spaces

Parameters

Returns: Promise<SpaceResponseShape>

Example

const space = await client.spaces.create({
  name: "Doc Space",
  spaceEmbedders: [{ embedderId: "your-embedder-id" }],
  labels: { env: "docs" },
});

client.spaces.delete

client.spaces.delete(id: string, requestOptions?: RequestOptions): Promise<void>

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

Returns: Promise<void>

Example

await client.spaces.delete("your-space-id");

client.spaces.get

client.spaces.get(id: string, requestOptions?: RequestOptions): Promise<SpaceResponseShape>

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

Returns: Promise<SpaceResponseShape>

Example

const fetchedSpace = await client.spaces.get("your-space-id");
console.log(fetchedSpace.name);

client.spaces.list

client.spaces.list(options?: SpacesListOptions, requestOptions?: RequestOptions): Promise<Page<SpaceResponseShape>>

Retrieves a list of spaces accessible to the caller, with optional filtering by owner, labels, and name. Results are paginated with a maximum number of spaces per response.

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

AUTHORIZATION: Requires LIST_SPACE on the GoodMem instance. Each returned space must also be visible through READ_SPACE; unauthorized spaces are filtered in PostgreSQL. The ownerId parameter filters that already-authorized result set and does not grant additional visibility.

DEFAULT SORT: Results ordered by created_at DESCENDING unless specified otherwise.

MAX_RESULTS CLAMPING: maxResults defaults to 50 and is clamped to [1, 1000] range.

HTTP: GET /v1/spaces

Parameters

Returns: Promise<Page<SpaceResponseShape>>

Example

Example 1:

for await (const item of await client.spaces.list()) {
  console.log(item.spaceId, item.name);
}

Example 2:

let seenSpaces = 0;
for await (const item of await client.spaces.list({ maxResults: 10 })) {
  console.log(item.name);
  if (++seenSpaces === 20) break;
}

Example 3:

const spacesPage = await client.spaces.list({ maxResults: 10 });
for (const item of spacesPage.items) {
  console.log(item.name);
}
if (spacesPage.nextToken) {
  await client.spaces.list({ nextToken: spacesPage.nextToken });
}

Example 4:

let token: string | undefined;
for (let pageCount = 0; pageCount < 3; pageCount++) {
  const nextPage = await client.spaces.list({ maxResults: 10, nextToken: token });
  console.log(nextPage.items.length);
  token = nextPage.nextToken;
  if (!token) break;
}

Example 5:

let emitted = 0;
for await (const item of await client.spaces.list()) {
  console.log(item.spaceId);
  if (++emitted >= 25) break;
}

Example 6:

const page = await client.spaces.list({ maxResults: 10 });
console.log(page.items.length, page.nextToken);

Example 7:

let cappedSpaces = 0;
for await (const item of await client.spaces.list({ maxResults: 5 })) {
  console.log(item.name);
  if (++cappedSpaces >= 12) break;
}

Example 8:

const firstSpacesPage = await client.spaces.list({ maxResults: 10 });
const resumedSpacesPage = await client.spaces.list({ nextToken: firstSpacesPage.nextToken });
console.log(resumedSpacesPage.items.length);

Example 9:

const resumeFrom = "opaque-next-token";
let resumedCount = 0;
for await (const item of await client.spaces.list({ nextToken: resumeFrom, maxResults: 10 })) {
  console.log(item.spaceId);
  if (++resumedCount >= 20) break;
}

client.spaces.transferOwnership

client.spaces.transferOwnership(id: string, request: TransferOwnershipRequest, requestOptions?: RequestOptions): Promise<TransferSpaceOwnershipResponseShape>

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

Returns: Promise<TransferSpaceOwnershipResponseShape>

Example

const transferredSpace = await client.spaces.transferOwnership(policySpaceId, {
  newOwnerId: principalId,
});

client.spaces.update

client.spaces.update(id: string, request: UpdateSpaceRequest, requestOptions?: RequestOptions): Promise<SpaceResponseShape>

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

Returns: Promise<SpaceResponseShape>

Example

const updatedSpace = await client.spaces.update("your-space-id", {
  name: "Doc Space (updated)",
  mergeLabels: { version: "2" },
});
console.log(updatedSpace.spaceId);

Data Models

Interfaces

ListSpacesResponse

Response containing a list of spaces and optional pagination token.

Space

A Space is a container for organizing related memories with vector embeddings.

SpaceCreationRequest

Request body for creating a new Space. A Space is a container for organizing related memories with vector embeddings.

SpaceEmbedder

Associates an embedder with a space, including retrieval configuration.

SpaceEmbedderConfig

Configuration for associating an embedder with a space.

TransferSpaceOwnershipResponse

The space after its ownership transfer completes.

UpdateSpaceRequest

Request parameters for updating a space.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

ListSpacesResponseShape

SpaceResponseShape

SpaceEmbedderResponseShape

TransferSpaceOwnershipResponseShape