GoodMemCreate a new Space
POST /v1/spaces: Creates a new space with the provided name, labels, and embedder configuration.
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.
ApiKeyAuthx-api-key<token>GoodMem-Timeout-Ms?integerOptional waiting budget in milliseconds, measured from REST servlet ingress and shared across all internal gRPC calls. Supply one decimal integer from 1 to 86400000. Omission adds no deadline. Existing shorter deadlines still apply. Expiry returns HTTP 504 before streaming starts; after streaming starts, no successful completion event is sent. Use SSE or opt into GoodMem-Stream-Terminal for an explicit terminal outcome. Retrieval work is cooperatively cancelled. An accepted mutation may still commit after timeout or disconnect; a failed response does not imply rollback.
int641 <= value <= 86400000Space configuration details
application/json- body
Request body for creating a new Space. A Space is a container for organizing related memories with vector embeddings.
name*stringThe desired name for the space. Must be unique within the user's scope.
1 <= length <= 255"My Research Space"labels?|A set of key-value pairs to categorize or tag the space. Used for filtering and organizational purposes.
properties <= 20{ "category": "research", "project": "ai-embeddings"}spaceEmbedders*array<>List of embedder configurations to associate with this space. At least one embedder configuration is required. Each specifies an embedder ID and a relative default retrieval weight used when no per-request overrides are provided.
1 <= items[ { "embedderId": "a867b266-2f63-485c-897d-3494669db253", "defaultRetrievalWeight": 1 }]ownerId?|Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_SPACE is evaluated against the proposed space and owner.
uuid"70e025f6-76ca-4cbe-b8fc-7dab8e84590a"defaultChunkingConfig*||Default chunking strategy for memories in this space
spaceId?|Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
uuid"550e8400-e29b-41d4-a716-446655440000"Successfully created space
application/json- response
A Space is a container for organizing related memories with vector embeddings.
spaceId*stringThe UUID for this space.
uuid"550e8400-e29b-41d4-a716-446655440000"name*stringThe name of the space.
1 <= length <= 255"Research Project Space"labels*Key-value pairs of metadata associated with the space.
{ "project": "AI Research", "team": "NLP Group"}spaceEmbedders*array<>The list of embedders associated with this space.
createdAt*integerTimestamp when this space was created (milliseconds since epoch).
int641651483320000updatedAt*integerTimestamp when this space was last updated (milliseconds since epoch).
int641651483320000ownerId*stringThe ID of the user who owns this space.
uuid"550e8400-e29b-41d4-a716-446655440000"createdById*stringThe ID of the user who created this space.
uuid"550e8400-e29b-41d4-a716-446655440000"updatedById*stringThe ID of the user who last updated this space.
uuid"550e8400-e29b-41d4-a716-446655440000"defaultChunkingConfig?||Default chunking strategy for memories in this space
{ "recursive": { "chunkSize": 1000, "chunkOverlap": 200, "separators": [ "\n\n", "\n", ".", " " ], "keepStrategy": "KEEP_END", "separatorIsRegex": false, "lengthMeasurement": "CHARACTER_COUNT" }, "sentence": { "maxChunkSize": 1000, "minChunkSize": 100, "enableLanguageDetection": true, "lengthMeasurement": "CHARACTER_COUNT" }}curl -X POST 'https://your-goodmem-server.example.com/v1/spaces' \ -H 'GoodMem-Timeout-Ms: 30000' \ -H 'Content-Type: application/json' \ -d '{ "name": "My Research Space", "labels": { "category": "research", "project": "ai-embeddings" }, "spaceEmbedders": [ { "embedderId": "a867b266-2f63-485c-897d-3494669db253", "defaultRetrievalWeight": 1 } ], "ownerId": "70e025f6-76ca-4cbe-b8fc-7dab8e84590a", "defaultChunkingConfig": { "recursive": { "chunkSize": 1000, "chunkOverlap": 200, "separators": [ "\\n\\n", "\\n", ".", " " ], "separatorIsRegex": false, "keepStrategy": "KEEP_END", "lengthMeasurement": "CHARACTER_COUNT" } }, "spaceId": "550e8400-e29b-41d4-a716-446655440000"}'{ "spaceId": "550e8400-e29b-41d4-a716-446655440000", "name": "Research Project Space", "labels": { "project": "AI Research", "team": "NLP Group" }, "spaceEmbedders": [ { "spaceId": "550e8400-e29b-41d4-a716-446655440000", "embedderId": "550e8400-e29b-41d4-a716-446655440000", "defaultRetrievalWeight": 1, "createdAt": 1651483320000, "updatedAt": 1651483320000, "createdById": "550e8400-e29b-41d4-a716-446655440000", "updatedById": "550e8400-e29b-41d4-a716-446655440000" } ], "createdAt": 1651483320000, "updatedAt": 1651483320000, "ownerId": "550e8400-e29b-41d4-a716-446655440000", "createdById": "550e8400-e29b-41d4-a716-446655440000", "updatedById": "550e8400-e29b-41d4-a716-446655440000", "defaultChunkingConfig": { "recursive": { "chunkSize": 1000, "chunkOverlap": 200, "separators": [ "\n\n", "\n", ".", " " ], "keepStrategy": "KEEP_END", "separatorIsRegex": false, "lengthMeasurement": "CHARACTER_COUNT" }, "sentence": { "maxChunkSize": 1000, "minChunkSize": 100, "enableLanguageDetection": true, "lengthMeasurement": "CHARACTER_COUNT" } }}