Spaces

Memory space management — the top-level container for memories.

Namespace: Goodmem.Client.Api · Class: SpacesApi

Reach this surface as client.Spaces on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.

Methods

CreateAsync

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.

Declaration

public Task<Space> CreateAsync(SpaceCreationRequest request, CancellationToken ct = default)

HTTP — POST /v1/spaces

Parameters

Returns

Task<Space> — an awaitable that resolves to Space.

Exceptions

Example

var space = await client.Spaces.CreateAsync(
    new SpaceCreationRequest
    {
        Name = "Doc Space",
        SpaceEmbedders = new[]
        {
            new SpaceEmbedderConfig
            {
                EmbedderId = "your-embedder-id",
                DefaultRetrievalWeight = 1.0,
            },
        },
        Labels = new Dictionary<string, string> { ["env"] = "docs" },
    }
);
Console.WriteLine(space.SpaceId);

GetAsync

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.

Declaration

public Task<Space> GetAsync(string id, CancellationToken ct = default)

HTTP — GET /v1/spaces/{id}

Parameters

Returns

Task<Space> — an awaitable that resolves to Space.

Exceptions

Example

var space = await client.Spaces.GetAsync("your-space-id");
Console.WriteLine(space.Name);

ListAsync

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.

Declaration

public IAsyncEnumerable<Space> ListAsync(SpacesListOptions? options = null, CancellationToken ct = default)

HTTP — GET /v1/spaces

Parameters

Returns

IAsyncEnumerable<Space> — an async stream; await foreach yields each Space across pages / events.

Exceptions

Examples

Example 1:

// Auto-paginate every space; the SDK fetches the next page on demand as you iterate.
await foreach (var space in client.Spaces.ListAsync())
    Console.WriteLine($"{space.SpaceId} {space.Name}");

Example 2:

// Auto-paginate but stop after 2 items total.
var count = 0;
await foreach (var space in client.Spaces.ListAsync())
{
    if (count >= 2)
        break;
    Console.WriteLine(space.SpaceId);
    count++;
}

Example 3:

// Process results a page at a time. MaxResults sets the server page size; the SDK
// fetches the next page on demand as you iterate.
var page = new List<Space>();
await foreach (
    var space in client.Spaces.ListAsync(new SpacesListOptions { MaxResults = 5 })
)
{
    page.Add(space);
    if (page.Count == 5)
    {
        // ... handle this page of results ...
        page.Clear();
    }
}
if (page.Count > 0)
{
    // ... handle the final partial page ...
}

Example 4:

// Page-at-a-time processing with a total cap across all pages.
var seen = 0;
var page = new List<Space>();
await foreach (
    var space in client.Spaces.ListAsync(new SpacesListOptions { MaxResults = 2 })
)
{
    page.Add(space);
    seen++;
    if (page.Count == 2)
        page.Clear();
    if (seen >= 2)
        break;
}

Example 5:

// Cap how many items you consume, regardless of page size.
var spaces = new List<Space>();
await foreach (var space in client.Spaces.ListAsync())
{
    if (spaces.Count >= 3)
        break;
    spaces.Add(space);
}

Example 6:

// MaxResults controls how many items the server returns per network call.
await foreach (
    var space in client.Spaces.ListAsync(new SpacesListOptions { MaxResults = 5 })
)
    Console.WriteLine(space.Name);

Example 7:

// Server batch size (MaxResults) and a client-side cap are independent:
// fetch 2 per API call, stop after 5 items total.
var count = 0;
await foreach (
    var space in client.Spaces.ListAsync(new SpacesListOptions { MaxResults = 2 })
)
{
    if (count >= 5)
        break;
    Console.WriteLine(space.SpaceId);
    count++;
}

Example 8:

// Resume from a pagination token you saved from an earlier page.
var savedToken = "your-saved-token";
await foreach (
    var space in client.Spaces.ListAsync(
        new SpacesListOptions { NextToken = savedToken }
    )
)
    Console.WriteLine(space.Name);

Example 9:

// Resume from a saved token but consume at most 10 more items.
var savedToken = "your-saved-token";
var count = 0;
await foreach (
    var space in client.Spaces.ListAsync(
        new SpacesListOptions { NextToken = savedToken }
    )
)
{
    if (count >= 10)
        break;
    Console.WriteLine(space.Name);
    count++;
}

UpdateAsync

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.

Declaration

public Task<Space> UpdateAsync(string id, UpdateSpaceRequest request, CancellationToken ct = default)

HTTP — PUT /v1/spaces/{id}

Parameters

Returns

Task<Space> — an awaitable that resolves to Space.

Exceptions

Example

var updated = await client.Spaces.UpdateAsync(
    "your-space-id",
    new UpdateSpaceRequest
    {
        Name = "Doc Space (updated)",
        MergeLabels = new Dictionary<string, string> { ["version"] = "2" },
    }
);
Console.WriteLine(updated.SpaceId);

DeleteAsync

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.

Declaration

public Task DeleteAsync(string id, CancellationToken ct = default)

HTTP — DELETE /v1/spaces/{id}

Parameters

Returns

Task — completes when the operation finishes; there is no response body.

Exceptions

Example

await client.Spaces.DeleteAsync("your-space-id");

TransferOwnershipAsync

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.

Declaration

public Task<TransferSpaceOwnershipResponse> TransferOwnershipAsync(string id, TransferOwnershipRequest request, CancellationToken ct = default)

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

Parameters

Returns

Task<TransferSpaceOwnershipResponse> — an awaitable that resolves to TransferSpaceOwnershipResponse.

Exceptions

Example

var transferredSpace = await client.Spaces.TransferOwnershipAsync(
    spaceId,
    new TransferOwnershipRequest { NewOwnerId = "your-principal-id" }
);

Data Models

Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.

SpaceCreationRequest

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

SpaceEmbedderConfig

Configuration for associating an embedder with a space.

Space

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

SpaceEmbedder

Associates an embedder with a space, including retrieval configuration.

ListSpacesResponse

Response containing a list of spaces and optional pagination token.

TransferSpaceOwnershipResponse

The space after its ownership transfer completes.

UpdateSpaceRequest

Request parameters for updating a space.