Spaces API

All URIs are relative to http://localhost:8080

Method	HTTP request	Description
createSpace	POST /v1/spaces	Create a new Space
deleteSpace	DELETE /v1/spaces/{id}	Delete a space
getSpace	GET /v1/spaces/{id}	Get a space by ID
listSpaces	GET /v1/spaces	List spaces
updateSpace	PUT /v1/spaces/{id}	Update a space

createSpace

Space createSpace(spaceCreationRequest)

Create a new Space

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 owner_id is provided (requires CREATE_SPACE_ANY if differs). EMBEDDER DEFAULTS: If no embedders are specified, a system-default embedder is attached. DUPLICATE DETECTION: Returns ALREADY_EXISTS if another space exists with identical {owner_id, name} (case-sensitive). Requires CREATE_SPACE_OWN permission (or CREATE_SPACE_ANY for admin users). This operation is NOT idempotent.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.SpacesApi();
let spaceCreationRequest = {"name":"My Research Space","spaceEmbedders":[{"embedderId":"a867b266-2f63-485c-897d-3494669db253","defaultRetrievalWeight":"1.0"}],"publicRead":"false","labels":{"category":"research","project":"ai-embeddings"},"defaultChunkingConfig":{"recursive":{"chunkSize":"1000","chunkOverlap":"200","separators":["\\n\\n","\\n","."," "],"keepStrategy":"KEEP_END","separatorIsRegex":"false","lengthMeasurement":"CHARACTER_COUNT"}}}; // SpaceCreationRequest | Space configuration details
apiInstance.createSpace(spaceCreationRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Name	Type	Description	Notes
spaceCreationRequest	SpaceCreationRequest	Space configuration details

Return type

Space

Authorization

No authorization required

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteSpace

deleteSpace(id)

Delete a space

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.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.SpacesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space to delete
apiInstance.deleteSpace(id).then(() => {
  console.log('API called successfully.');
}, (error) => {
  console.error(error);
});

Parameters

Name	Type	Description	Notes
id	String	The unique identifier of the space to delete

Return type

null (empty response body)

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: Not defined

getSpace

Space getSpace(id)

Get a space by 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.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.SpacesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space to retrieve
apiInstance.getSpace(id).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Name	Type	Description	Notes
id	String	The unique identifier of the space to retrieve

Return type

Space

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

listSpaces

ListSpacesResponse listSpaces(opts)

List spaces

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. PERMISSION-BASED FILTERING: With LIST_SPACE_ANY and owner_id 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: max_results defaults to 50 and is clamped to [1, 1000] range. Requires LIST_SPACE_OWN or LIST_SPACE_ANY permission.

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.SpacesApi();
let opts = {
  'ownerId': "550e8400-e29b-41d4-a716-446655440000", // String | Filter spaces by owner ID. With LIST_SPACE_ANY permission and owner_id omitted, returns all visible spaces. Otherwise returns caller-owned spaces only. Specifying owner_id without LIST_SPACE_ANY returns PERMISSION_DENIED.
  'nameFilter': "Research*", // String | Filter spaces by name using glob pattern matching
  'maxResults': 20, // Number | Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000])
  'nextToken': "eyJzdGFydCI6MjAsIm93bmVySWQiOiJiMzMwM2QwYS0...", // String | Pagination token for retrieving the next set of results
  'sortBy': "name", // String | Field to sort by: 'created_at' or 'name' (default: 'created_at'). Unsupported values return INVALID_ARGUMENT.
  'sortOrder': "ASCENDING", // String | Sort order (ASCENDING or DESCENDING, default: DESCENDING)
  'label': "?label.project=AI&label.team=NLP" // String | Filter by label value. Multiple label filters can be specified (e.g., ?label.project=AI&label.team=NLP)
};
apiInstance.listSpaces(opts).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Name	Type	Description	Notes
ownerId	String	Filter spaces by owner ID. With LIST_SPACE_ANY permission and owner_id omitted, returns all visible spaces. Otherwise returns caller-owned spaces only. Specifying owner_id without LIST_SPACE_ANY returns PERMISSION_DENIED.	[optional]
nameFilter	String	Filter spaces by name using glob pattern matching	[optional]
maxResults	Number	Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000])	[optional]
nextToken	String	Pagination token for retrieving the next set of results	[optional]
sortBy	String	Field to sort by: 'created_at' or 'name' (default: 'created_at'). Unsupported values return INVALID_ARGUMENT.	[optional]
sortOrder	String	Sort order (ASCENDING or DESCENDING, default: DESCENDING)	[optional]
label	String	Filter by label value. Multiple label filters can be specified (e.g., ?label.project=AI&label.team=NLP)	[optional]

Return type

ListSpacesResponse

Authorization

No authorization required

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateSpace

Space updateSpace(id, updateSpaceRequest)

Update a space

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

Example

import GoodMemClient from '@pairsystems/goodmem-client';

let apiInstance = new GoodMemClient.SpacesApi();
let id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space to update
let updateSpaceRequest = {"name":"Updated Research Space","publicRead":"true","replaceLabels":{"category":"updated-research","project":"ai-embedding-project"}}; // UpdateSpaceRequest | Space update details
apiInstance.updateSpace(id, updateSpaceRequest).then((data) => {
  console.log('API called successfully. Returned data: ' + data);
}, (error) => {
  console.error(error);
});

Parameters

Name	Type	Description	Notes
id	String	The unique identifier of the space to update
updateSpaceRequest	UpdateSpaceRequest	Space update details

Content-Type: application/json
Accept: application/json

Spaces API

On this page