Spaces API

Organize memories into logical groups. Spaces provide isolation and context boundaries for your agent's knowledge.

Updated Oct 6, 2026

Overview

Spaces are containers that organize your memories into logical groups. Use spaces to separate different contexts, users, or domains of knowledge. Each memory belongs to exactly one space.

Creating your first space: Call POST /spaces once per account to provision a space. Memories and clusters can then be scoped to that space's UUID.

Create Space

`POST /spaces` — Create a new space

Creates a new space for organizing memories. Space names must be unique within your account.

Body Parameters

Name	Type	Required	Description
`name`	`string`	yes	Space name (1-255 chars). Unique per account.
`slug`	`string`	no	Optional URL-safe identifier. Auto-generated from name if omitted. Matches `^[a-z0-9][a-z0-9-]*[a-z0-9]$`, max 255 chars.
`description`	`string`	no	Optional description (max 1000 chars).

Response (201)

Returns the created space with has_access and permission fields for the calling API key.

POST /spaces — request

{
  "name": "Engineering Docs",
  "description": "Technical documentation and architecture decisions"
}

POST /spaces — response

{
  "id": "<uuid>",
  "name": "Engineering Docs",
  "slug": "engineering-docs",
  "description": "Technical documentation and architecture decisions",
  "has_access": true,
  "permission": "admin",
  "created_at": "2026-04-10T10:30:00Z"
}

Get Space

`GET /spaces/:id` — Retrieve a space

Fetches a space by its ID or name. Returns space details including memory count.

Path Parameters

Name	Type	Required	Description
`spaceId`	`string`	yes	The space UUID or current/historical slug.

Response (200)

Returns the space plus has_access, permission, and api_keys_with_access.

Slug Redirects: When accessing a space by an old slug (after it was changed), the API returns a 301 redirect to the new slug location.

GET /spaces/engineering-docs

{
  "id": "<uuid>",
  "name": "Engineering Docs",
  "slug": "engineering-docs",
  "description": "Technical documentation and architecture decisions",
  "memory_count": 1247,
  "has_access": true,
  "permission": "admin",
  "api_keys_with_access": [
    { "id": "<uuid>", "name": "default", "permission": "admin" }
  ],
  "created_at": "2026-04-10T10:30:00Z",
  "updated_at": "2026-04-14T14:22:00Z"
}

List Spaces

`GET /spaces` — List all spaces

Returns a list of all spaces in your account, ordered by creation date.

Query Parameters

Name	Type	Required	Description
`include_system`	`boolean`	no	Include system spaces (e.g. agent private spaces) in the list. Default: false.

Response (200)

Returns { spaces: [...] }. Each space is annotated with has_access and permission for the calling API key. The endpoint is not paginated.

GET /spaces

{
  "spaces": [
    {
      "id": "<uuid>",
      "name": "default",
      "slug": "default",
      "description": "Default space",
      "memory_count": 523,
      "has_access": true,
      "permission": "admin",
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "<uuid>",
      "name": "Engineering Docs",
      "slug": "engineering-docs",
      "description": "Technical documentation and architecture decisions",
      "memory_count": 1247,
      "has_access": true,
      "permission": "read_write",
      "created_at": "2026-04-10T10:30:00Z"
    }
  ]
}

Update Space

`PATCH /spaces/:id` — Update a space

Updates an existing space. Only the fields you provide will be updated.

Path Parameters

Name	Type	Required	Description
`spaceId`	`string`	yes	The space UUID or current slug.

Body Parameters

Name	Type	Required	Description
`name`	`string`	no	New name for the space.
`slug`	`string`	no	New URL-safe slug. The old slug continues to resolve via 301 redirect.
`description`	`string`	no	New description (nullable).
`ingestion_enrichment_profile`	`string \| null`	no	Registered enrichment profile name, or `null` to fall back to the account default (ADR-109a).

Response (200)

Returns the updated space object.

Slug History: When you update a space's slug, the old slug continues to work. GET requests to old slugs return a 301 redirect to the new slug.

PATCH /spaces/engineering-docs — request

{
  "slug": "eng-docs",
  "description": "Technical docs, ADRs, and architecture decisions"
}

PATCH /spaces/engineering-docs — response

{
  "id": "<uuid>",
  "name": "Engineering Docs",
  "slug": "eng-docs",
  "description": "Technical docs, ADRs, and architecture decisions",
  "memory_count": 1247,
  "created_at": "2026-04-10T10:30:00Z",
  "updated_at": "2026-04-14T09:15:00Z"
}

Delete Space

`DELETE /spaces/:id` — Delete a space

Deletes a space and all memories within it. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`spaceId`	`string`	yes	The space UUID or slug.

Response (204)

Returns no content on successful deletion.

Warning: Deleting a space permanently removes all memories within it. This action cannot be undone. The default space cannot be deleted.

Permanently merges source_space_id into the space in the path: the source's memories, relationships, and clusters move to the target, then the source space is removed. Because it can't be undone, confirm is required.

POST /spaces/:id/merge — request

POST /spaces/<target-id>/merge

{
  "source_space_id": "<source-uuid-or-slug>",
  "confirm": true
}

Warning: Merging is irreversible. Export the source space first if you might need the split back.

Link Spaces

`POST /spaces/:id/links` — Link two spaces

Creates a reversible link between the space in the path and target_space_id. Linked spaces can share access and form cross-space relationships without merging; remove the link to separate them again.

POST /spaces/:id/links — request

POST /spaces/<space-id>/links

{
  "target_space_id": "<other-uuid-or-slug>"
}

Space Object

The space object contains the following fields:

Field	Type	Description
`id`	`string`	UUID identifier for the space.
`name`	`string`	Display name for the space.
`slug`	`string`	URL-safe identifier for the space. Auto-generated from name or custom.
`description`	`string \| null`	Optional description.
`is_system`	`boolean`	Whether this space is a system space (e.g. an agent's private space). Hidden from the list unless `include_system=true`.
`ingestion_enrichment_profile`	`string \| null`	Enrichment profile override for this space (ADR-109a).
`memory_count`	`integer`	Number of memories stored in this space (populated by `GET /spaces/:spaceId`).
`has_access`	`boolean`	Whether the calling API key has access to this space.
`permission`	`string \| null`	Permission level for the calling API key: `read`, `read_write`, or `admin`.
`created_at`	`string`	ISO 8601 timestamp of when the space was created.
`updated_at`	`string`	ISO 8601 timestamp of when the space was last updated.

Use Cases

Multi-tenant Applications

Create a separate space for each user or organization to ensure complete data isolation:

user-{user_id} — Per-user memory storage
org-{org_id} — Organization-level shared knowledge

Domain Separation

Organize knowledge by domain or topic for more relevant search results:

product-docs — Product documentation
customer-interactions — Customer conversation history
internal-policies — Internal company policies

Environment Isolation

Separate development and production data:

dev-testing — Development and testing memories
production — Production memory storage

Spaces API

Overview

Create Space

`POST /spaces` — Create a new space

Body Parameters

Response (201)

Get Space

`GET /spaces/:id` — Retrieve a space

Path Parameters

Response (200)

List Spaces

`GET /spaces` — List all spaces

Query Parameters

Response (200)

Update Space

`PATCH /spaces/:id` — Update a space

Path Parameters

Body Parameters

Response (200)

Delete Space

`DELETE /spaces/:id` — Delete a space

Path Parameters

Response (204)

Merge Space

`POST /spaces/:id/merge` — Merge a space into this one

Link Spaces

`POST /spaces/:id/links` — Link two spaces

Space Object

Use Cases

Multi-tenant Applications

Domain Separation

Environment Isolation

POST /spaces — Create a new space

Body Parameters

Response (201)

GET /spaces/:id — Retrieve a space

Path Parameters

Response (200)

GET /spaces — List all spaces

Query Parameters

Response (200)

PATCH /spaces/:id — Update a space

Path Parameters

Body Parameters

Response (200)

DELETE /spaces/:id — Delete a space

Path Parameters

Response (204)

POST /spaces/:id/merge — Merge a space into this one

POST /spaces/:id/links — Link two spaces

Multi-tenant Applications

Domain Separation

Environment Isolation

`POST /spaces` — Create a new space

`GET /spaces/:id` — Retrieve a space

`GET /spaces` — List all spaces

`PATCH /spaces/:id` — Update a space

`DELETE /spaces/:id` — Delete a space

`POST /spaces/:id/merge` — Merge a space into this one

`POST /spaces/:id/links` — Link two spaces