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 REQUIREMENTS: At least one embedder configuration must be specified.

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

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

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

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://loading/v1/spaces" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Research Space",
    "spaceEmbedders": [
      {
        "embedderId": "a867b266-2f63-485c-897d-3494669db253",
        "defaultRetrievalWeight": 1
      }
    ],
    "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"
      }
    }
  }'

curl -X POST "https://loading/v1/spaces" \  -H "Content-Type: application/json" \  -d '{    "name": "My Research Space",    "spaceEmbedders": [      {        "embedderId": "a867b266-2f63-485c-897d-3494669db253",        "defaultRetrievalWeight": 1      }    ],    "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"      }    }  }'

{
  "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": {
    "none": null,
    "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