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 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.

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_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

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. 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

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). PERMISSION-BASED FILTERING: With LIST_SPACE_ANY and ownerId omitted, returns all visible spaces; otherwise returns caller-owned spaces only. 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. Requires LIST_SPACE_OWN or LIST_SPACE_ANY permission.

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.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, 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

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.

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