Create a space — REST API

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.

Request Body

Space configuration details

namestring

The desired name for the space. Must be unique within the user's scope.

Example"My Research Space"

Length1 <= length <= 255

labels?object | null

A set of key-value pairs to categorize or tag the space. Used for filtering and organizational purposes.

Example{"category":"research","project":"ai-embeddings"}

Propertiesproperties <= 20

Empty Object

spaceEmbeddersarray<SpaceEmbedderConfig>

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.

Example[{"embedderId":"a867b266-2f63-485c-897d-3494669db253","defaultRetrievalWeight":1}]

Items1 <= items

ownerId?string | null

Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_SPACE is evaluated against the proposed space and owner.

Example"70e025f6-76ca-4cbe-b8fc-7dab8e84590a"

Formatuuid

defaultChunkingConfigChunkingConfiguration

Default chunking strategy for memories in this space

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

noneNoChunkingConfiguration | null

No chunking strategy - preserve original content as single unit

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

recursiveRecursiveChunkingConfiguration | null

Recursive hierarchical chunking strategy with configurable separators

Example

{"chunkSize":1000,"chunkOverlap":200,"separators":["\n\n","\n","."," "],"keepStrategy":"KEEP_END","separatorIsRegex":false,"lengthMeasurement":"CHARACTER_COUNT"}

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

sentenceSentenceChunkingConfiguration | null

Sentence-based chunking strategy with language detection

Example{"maxChunkSize":1000,"minChunkSize":100,"enableLanguageDetection":true,"lengthMeasurement":"CHARACTER_COUNT"}

spaceId?string | null

Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.

Example"550e8400-e29b-41d4-a716-446655440000"

Formatuuid

Response Body

curl -X POST "https://your-goodmem-server.example.com/v1/spaces" \
  -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"
  }'

curl -X POST "https://your-goodmem-server.example.com/v1/spaces" \  -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"
    }
  }
}

Empty

Create a new Space

Authorization

Request Body

Response Body

Create a new Space

Authorization

Request Body

Response Body

201

400

401

403

409