Spaces API
Spaces API documentation for Python SDK
All URIs are relative to http://localhost:8080
| Method | HTTP request | Description |
|---|---|---|
| create_space | POST /v1/spaces | Create a new Space |
| delete_space | DELETE /v1/spaces/{id} | Delete a space |
| get_space | GET /v1/spaces/{id} | Get a space by ID |
| list_spaces | GET /v1/spaces | List spaces |
| update_space | PUT /v1/spaces/{id} | Update a space |
create_space
Space create_space(space_creation_request)
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
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.space import Space
from goodmem_client.models.space_creation_request import SpaceCreationRequest
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.SpacesApi(api_client)
space_creation_request = {"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
try:
# Create a new Space
api_response = api_instance.create_space(space_creation_request)
print("The response of SpacesApi->create_space:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling SpacesApi->create_space: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| space_creation_request | SpaceCreationRequest | Space configuration details |
Return type
Authorization
HTTP request headers
- Content-Type: application/json
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 201 | Successfully created space | - |
| 400 | Invalid request - missing required fields or invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to create spaces | - |
| 409 | Conflict - space with same name already exists for this owner | - |
delete_space
delete_space(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
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.SpacesApi(api_client)
id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the space to delete
try:
# Delete a space
api_instance.delete_space(id)
except Exception as e:
print("Exception when calling SpacesApi->delete_space: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the space to delete |
Return type
void (empty response body)
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: Not defined
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 204 | Space successfully deleted | - |
| 400 | Invalid request - space ID in invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to delete this space | - |
| 404 | Not found - space with the specified ID does not exist | - |
get_space
Space get_space(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
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.space import Space
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.SpacesApi(api_client)
id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the space to retrieve
try:
# Get a space by ID
api_response = api_instance.get_space(id)
print("The response of SpacesApi->get_space:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling SpacesApi->get_space: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the space to retrieve |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully retrieved space | - |
| 400 | Invalid request - space ID in invalid format | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to view this space | - |
| 404 | Not found - space with the specified ID does not exist | - |
list_spaces
ListSpacesResponse list_spaces(owner_id=owner_id, name_filter=name_filter, max_results=max_results, next_token=next_token, sort_by=sort_by, sort_order=sort_order, label_=label_)
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
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.list_spaces_response import ListSpacesResponse
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.SpacesApi(api_client)
owner_id = '550e8400-e29b-41d4-a716-446655440000' # str | 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)
name_filter = 'Research*' # str | Filter spaces by name using glob pattern matching (optional)
max_results = 20 # int | Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000]) (optional)
next_token = 'eyJzdGFydCI6MjAsIm93bmVySWQiOiJiMzMwM2QwYS0...' # str | Pagination token for retrieving the next set of results (optional)
sort_by = 'name' # str | Field to sort by: 'created_at' or 'name' (default: 'created_at'). Unsupported values return INVALID_ARGUMENT. (optional)
sort_order = 'ASCENDING' # str | Sort order (ASCENDING or DESCENDING, default: DESCENDING) (optional)
label_ = '?label.project=AI&label.team=NLP' # str | Filter by label value. Multiple label filters can be specified (e.g., ?label.project=AI&label.team=NLP) (optional)
try:
# List spaces
api_response = api_instance.list_spaces(owner_id=owner_id, name_filter=name_filter, max_results=max_results, next_token=next_token, sort_by=sort_by, sort_order=sort_order, label_=label_)
print("The response of SpacesApi->list_spaces:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling SpacesApi->list_spaces: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| owner_id | str | 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] |
| name_filter | str | Filter spaces by name using glob pattern matching | [optional] |
| max_results | int | Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000]) | [optional] |
| next_token | str | Pagination token for retrieving the next set of results | [optional] |
| sort_by | str | Field to sort by: 'created_at' or 'name' (default: 'created_at'). Unsupported values return INVALID_ARGUMENT. | [optional] |
| sort_order | str | Sort order (ASCENDING or DESCENDING, default: DESCENDING) | [optional] |
| label_ | str | Filter by label value. Multiple label filters can be specified (e.g., ?label.project=AI&label.team=NLP) | [optional] |
Return type
Authorization
HTTP request headers
- Content-Type: Not defined
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully retrieved spaces | - |
| 400 | Invalid request - invalid filter parameters or pagination token | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to list spaces | - |
update_space
Space update_space(id, update_space_request)
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
- Api Key Authentication (ApiKeyAuth):
import goodmem_client
from goodmem_client.models.space import Space
from goodmem_client.models.update_space_request import UpdateSpaceRequest
from goodmem_client.rest import ApiException
from pprint import pprint
# Defining the host is optional and defaults to http://localhost:8080/v1/default
# See configuration.py for a list of all supported configuration parameters.
configuration = goodmem_client.Configuration(
host = "http://localhost:8080/v1/default"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]
# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
# Enter a context with an instance of the API client
with goodmem_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = goodmem_client.SpacesApi(api_client)
id = '550e8400-e29b-41d4-a716-446655440000' # str | The unique identifier of the space to update
update_space_request = {"name":"Updated Research Space","publicRead":"true","replaceLabels":{"category":"updated-research","project":"ai-embedding-project"}} # UpdateSpaceRequest | Space update details
try:
# Update a space
api_response = api_instance.update_space(id, update_space_request)
print("The response of SpacesApi->update_space:\n")
pprint(api_response)
except Exception as e:
print("Exception when calling SpacesApi->update_space: %s\n" % e)Parameters
| Name | Type | Description | Notes |
|---|---|---|---|
| id | str | The unique identifier of the space to update | |
| update_space_request | UpdateSpaceRequest | Space update details |
Return type
Authorization
HTTP request headers
- Content-Type: application/json
- Accept: application/json
HTTP response details
| Status code | Description | Response headers |
|---|---|---|
| 200 | Successfully updated space | - |
| 400 | Invalid request - ID format or update parameters invalid | - |
| 401 | Unauthorized - invalid or missing API key | - |
| 403 | Forbidden - insufficient permissions to update this space | - |
| 404 | Not found - space with the specified ID does not exist | - |
| 409 | Conflict - name conflicts with existing space for this owner | - |