REST API: Spaces & Clusters

Organize memories into spaces and discover clusters in the Trix REST API.

Updated Oct 6, 2026

Overview

Spaces provide logical isolation for memories, perfect for multi-tenant applications or organizing different knowledge domains. Clusters are automatically discovered groupings of semantically related memories within a space.

Spaces

Manual organization with access control. Ideal for tenants, projects, or domains.

Clusters

Auto-discovered topic groups. Emerge from memory content and relationships.

Managing Spaces

Create Space

Create a new space to isolate memories for a tenant, project, or domain:

create-space.sh

curl -X POST "https://api.trixdb.com/v1/spaces" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support",
    "slug": "support",
    "description": "Support ticket context and resolutions"
  }'

# Response (201 Created)
{
  "id": "<uuid>",
  "name": "Customer Support",
  "slug": "support",
  "description": "Support ticket context and resolutions",
  "created_at": "2026-04-15T10:30:00Z",
  "updated_at": "2026-04-15T10:30:00Z"
}

POST /v1/spaces accepts only name (required, 1-255 chars), slug (optional, lowercase letters/numbers/hyphens, auto-generated if omitted), and description (optional, ≤1000 chars). If you send additional fields they will be silently discarded by the Fastify schema.

Updating a space

PATCH /v1/spaces/:spaceId accepts name, slug, description, and ingestion_enrichment_profile (set to null to use the account default, or a registered profile name).

Planned. Per-space settings such as auto_clustering, a choice of embedding_model, and retention_days are on the roadmap but not yet writable via POST /v1/spaces. Cluster generation runs automatically today; embedding model is account-wide; retention is not configurable.

List Spaces

list-spaces.sh

curl -X GET "https://api.trixdb.com/v1/spaces" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Optional: include system/agent-private spaces
curl -X GET "https://api.trixdb.com/v1/spaces?include_system=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response (returns every non-system space the account owns; key access is marked)
{
  "spaces": [
    {
      "id": "<uuid>",
      "name": "Default",
      "slug": "default",
      "description": null,
      "created_at": "2026-01-15T10:30:00Z",
      "has_access": true,
      "permission": "admin"
    },
    {
      "id": "<uuid>",
      "name": "Customer Support",
      "slug": "support",
      "description": "Support ticket context and resolutions",
      "created_at": "2026-03-01T12:00:00Z",
      "has_access": true,
      "permission": "read_write"
    }
  ]
}

Update Space

update-space.sh

# Update space by slug (or ID)
curl -X PATCH "https://api.trixdb.com/v1/spaces/support" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Success",
    "slug": "customer-success",
    "description": "Post-sale customer success knowledge",
    "ingestion_enrichment_profile": "default"
  }'

When you update a space's slug, the old slug will continue to work and redirect to the new slug with a 301 status code. This ensures existing integrations keep working.

Access by Slug

Spaces can be accessed using either their ID or slug. Using slugs makes your API calls more readable and easier to understand:

access-by-slug.sh

# Access by slug (human-friendly)
curl -X GET "https://api.trixdb.com/v1/spaces/support" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Access by ID (also works)
curl -X GET "https://api.trixdb.com/v1/spaces/space_cs_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Old slugs redirect with 301
# If you renamed "support" to "customer-success":
curl -X GET "https://api.trixdb.com/v1/spaces/support"
# Returns 301 redirect to /spaces/customer-success

Delete Space

Deleting a space permanently removes all memories and clusters within it. This action cannot be undone.

delete-space.sh

curl -X DELETE "https://api.trixdb.com/v1/spaces/space_cs_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Force delete (skip confirmation)
curl -X DELETE "https://api.trixdb.com/v1/spaces/space_cs_abc123?force=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Using Spaces

When creating or querying memories, specify the space using the space_id parameter or header. You can use either the space ID or slug:

Create Memory in Space

memory-in-space.sh

# Use space_id in request body
curl -X POST "https://api.trixdb.com/v1/memories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customer reported billing issue resolved by refund",
    "space_id": "space_cs_abc123"
  }'

Query Within Space

query-space.sh

# Search memories in specific space
curl -X GET "https://api.trixdb.com/v1/memories?q=billing+issue&space_id=space_cs_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Search across multiple spaces
curl -X GET "https://api.trixdb.com/v1/memories?q=billing+issue&space_ids=space_cs_abc123,space_billing" \
  -H "Authorization: Bearer YOUR_API_KEY"

API keys can be scoped to specific spaces for security. A key scoped to space_cs_abc123 cannot access memories in other spaces.

Working with Clusters

Clusters are automatically discovered groups of semantically related memories. Trix continuously analyzes your memory graph to identify and update clusters.

List Clusters

list-clusters.sh

curl -X GET "https://api.trixdb.com/v1/clusters?space_id=space_cs_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "clusters": [
    {
      "id": "cluster_billing",
      "name": "Billing & Payments",
      "description": "Issues related to invoicing, refunds, and payment processing",
      "memory_count": 342,
      "keywords": ["billing", "invoice", "refund", "payment", "charge"],
      "centroid_memory_id": "mem_billing_001",
      "coherence_score": 0.87,
      "created_at": "2024-01-10T08:00:00Z",
      "updated_at": "2024-01-15T12:30:00Z"
    }
  ],
  "total": 28
}

Get Cluster Details

get-cluster.sh

curl -X GET "https://api.trixdb.com/v1/clusters/cluster_billing?include_memories=true&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rename Cluster

Update cluster name and description (auto-generated names can be improved):

rename-cluster.sh

curl -X PATCH "https://api.trixdb.com/v1/clusters/cluster_billing" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing Issues & Refunds",
    "description": "Customer billing problems and resolution patterns"
  }'

Cluster-Based Search

Use clusters to scope searches:

cluster-search.sh

# Search within a cluster
curl -X GET "https://api.trixdb.com/v1/memories?q=refund+policy&cluster_id=cluster_billing" \
  -H "Authorization: Bearer YOUR_API_KEY"

Code Examples

Multi-Tenant Setup

async function setupTenant(tenantId: string) {
  const space = await fetch('https://api.trixdb.com/v1/spaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${adminKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: tenantId,
      metadata: { tenant_id: tenantId }
    })
  }).then(r => r.json());

  const key = await fetch('https://api.trixdb.com/v1/accounts/api-keys', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${adminKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: `${tenantId} Backend`,
      permissions: 'read_write',
      space_ids: [space.id]
    })
  }).then(r => r.json());

  return { space, key };
}

Browse Clusters

const clusters = await fetch(
  'https://api.trixdb.com/v1/clusters?include_top_memories=3',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
).then(r => r.json());

clusters.clusters.forEach(cluster => {
  console.log(`${cluster.name} (${cluster.memory_count} memories)`);
  cluster.top_memories.forEach(m => {
    console.log(`  - ${m.content.slice(0, 50)}...`);
  });
});

Endpoints Reference

Spaces

Method	Endpoint	Description
`POST`	`/spaces`	Create space (with optional slug)
`GET`	`/spaces`	List spaces
`GET`	`/spaces/:id_or_slug`	Get space by ID or slug
`PATCH`	`/spaces/:id_or_slug`	Update space (including slug)
`DELETE`	`/spaces/:id_or_slug`	Delete space

Clusters

Method	Endpoint	Description
`GET`	`/clusters`	List clusters
`GET`	`/clusters/:id`	Get cluster details
`PATCH`	`/clusters/:id`	Update cluster name/description