GoodMem
ReferenceClient SDKsJava SDK

Spaces API

Spaces API documentation for Java SDK

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

MethodHTTP requestDescription
createSpacePOST /v1/spacesCreate a new Space
deleteSpaceDELETE /v1/spaces/{id}Delete a space
getSpaceGET /v1/spaces/{id}Get a space by ID
listSpacesGET /v1/spacesList spaces
updateSpacePUT /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 classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.SpacesApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    SpacesApi apiInstance = new SpacesApi(defaultClient);
    SpaceCreationRequest spaceCreationRequest = new SpaceCreationRequest(); // SpaceCreationRequest | Space configuration details
    try {
      Space result = apiInstance.createSpace(spaceCreationRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SpacesApi#createSpace");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
spaceCreationRequestSpaceCreationRequestSpace configuration details

Return type

Space

Authorization

ApiKeyAuth

HTTP request headers

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

HTTP response details

Status codeDescriptionResponse headers
201Successfully created space-
400Invalid request - missing required fields or invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to create spaces-
409Conflict - space with same name already exists for this owner-

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 classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.SpacesApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    SpacesApi apiInstance = new SpacesApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space to delete
    try {
      apiInstance.deleteSpace(id);
    } catch (ApiException e) {
      System.err.println("Exception when calling SpacesApi#deleteSpace");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the space to delete

Return type

null (empty response body)

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

HTTP response details

Status codeDescriptionResponse headers
204Space successfully deleted-
400Invalid request - space ID in invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to delete this space-
404Not found - space with the specified ID does not exist-

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 classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.SpacesApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    SpacesApi apiInstance = new SpacesApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space to retrieve
    try {
      Space result = apiInstance.getSpace(id);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SpacesApi#getSpace");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the space to retrieve

Return type

Space

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully retrieved space-
400Invalid request - space ID in invalid format-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to view this space-
404Not found - space with the specified ID does not exist-

listSpaces

ListSpacesResponse listSpaces(ownerId, nameFilter, maxResults, nextToken, sortBy, sortOrder, labelStar)

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 classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.SpacesApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    SpacesApi apiInstance = new SpacesApi(defaultClient);
    String 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.
    String nameFilter = "Research*"; // String | Filter spaces by name using glob pattern matching
    Integer maxResults = 20; // Integer | Maximum number of results to return in a single page (defaults to 50, clamped to [1, 1000])
    String nextToken = "eyJzdGFydCI6MjAsIm93bmVySWQiOiJiMzMwM2QwYS0..."; // String | Pagination token for retrieving the next set of results
    String sortBy = "name"; // String | Field to sort by: 'created_at' or 'name' (default: 'created_at'). Unsupported values return INVALID_ARGUMENT.
    String sortOrder = "ASCENDING"; // String | Sort order (ASCENDING or DESCENDING, default: DESCENDING)
    String labelStar = "?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)
    try {
      ListSpacesResponse result = apiInstance.listSpaces(ownerId, nameFilter, maxResults, nextToken, sortBy, sortOrder, labelStar);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SpacesApi#listSpaces");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
ownerIdStringFilter 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]
nameFilterStringFilter spaces by name using glob pattern matching[optional]
maxResultsIntegerMaximum number of results to return in a single page (defaults to 50, clamped to [1, 1000])[optional]
nextTokenStringPagination token for retrieving the next set of results[optional]
sortByStringField to sort by: 'created_at' or 'name' (default: 'created_at'). Unsupported values return INVALID_ARGUMENT.[optional]
sortOrderStringSort order (ASCENDING or DESCENDING, default: DESCENDING)[optional]
labelStarStringFilter by label value. Multiple label filters can be specified (e.g., ?label.project=AI&label.team=NLP)[optional]

Return type

ListSpacesResponse

Authorization

ApiKeyAuth

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status codeDescriptionResponse headers
200Successfully retrieved spaces-
400Invalid request - invalid filter parameters or pagination token-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to list spaces-

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 classes:
import ai.pairsys.goodmem.client.ApiClient;
import ai.pairsys.goodmem.client.ApiException;
import ai.pairsys.goodmem.client.Configuration;
import ai.pairsys.goodmem.client.auth.*;
import ai.pairsys.goodmem.client.models.*;
import ai.pairsys.goodmem.client.api.SpacesApi;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("[http://localhost:8080](http://localhost:8080)");
    
    // Configure API key authorization: ApiKeyAuth
    ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    ApiKeyAuth.setApiKey("YOUR API KEY");
    // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
    //ApiKeyAuth.setApiKeyPrefix("Token");

    SpacesApi apiInstance = new SpacesApi(defaultClient);
    String id = "550e8400-e29b-41d4-a716-446655440000"; // String | The unique identifier of the space to update
    UpdateSpaceRequest updateSpaceRequest = new UpdateSpaceRequest(); // UpdateSpaceRequest | Space update details
    try {
      Space result = apiInstance.updateSpace(id, updateSpaceRequest);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SpacesApi#updateSpace");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Parameters

NameTypeDescriptionNotes
idStringThe unique identifier of the space to update
updateSpaceRequestUpdateSpaceRequestSpace update details

Return type

Space

Authorization

ApiKeyAuth

HTTP request headers

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

HTTP response details

Status codeDescriptionResponse headers
200Successfully updated space-
400Invalid request - ID format or update parameters invalid-
401Unauthorized - invalid or missing API key-
403Forbidden - insufficient permissions to update this space-
404Not found - space with the specified ID does not exist-
409Conflict - name conflicts with existing space for this owner-

Rerankers API

Rerankers API documentation for Java SDK

System API

System API documentation for Java SDK

On this page

createSpaceExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsdeleteSpaceExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsgetSpaceExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailslistSpacesExampleParametersReturn typeAuthorizationHTTP request headersHTTP response detailsupdateSpaceExampleParametersReturn typeAuthorizationHTTP request headersHTTP response details