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 ownerId 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 {ownerId, name} (case-sensitive). Requires CREATE_SPACE_OWN permission (or CREATE_SPACE_ANY for admin users). This operation is NOT idempotent.

Authorization

x-api-key<token>

In: header

Request Body

Space configuration details

namestring

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

Default"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.

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

Propertiesproperties <= 20

Empty Object

spaceEmbeddersarray<SpaceEmbedderConfig>

List of embedder configurations to associate with this space. Each specifies an embedder ID and a relative default retrieval weight used when no per-request overrides are provided.

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

Items1 <= items

publicRead?boolean | null

Indicates if the space and its memories can be read by unauthenticated users or users other than the owner. Defaults to false.

Defaultfalse

ownerId?string | null

Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_SPACE_ANY permission if specified.

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

Default

{"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

Default{"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.

Formatuuid

Response Body

curl -X POST "http://localhost:8080/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
      }
    ],
    "publicRead": false,
    "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 "http://localhost:8080/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      }    ],    "publicRead": false,    "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",
  "publicRead": false,
  "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

201

400

401

403

409