---
title: Clusters and namespaces
description: Isolate tenants within a cluster and identify their resources.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Clusters and namespaces

A cluster is one Graphon Engine deployment with a base URL and capabilities. A namespace is the tenant isolation boundary inside that cluster.

## One cluster, many tenants

*Illustration: The Acme and Northwind tenants use separate namespaces on one cluster. Each namespace has its own collections and files.*

Use a namespace for each customer or application that needs an independent data boundary. A single-tenant deployment can use one namespace. The API model stays the same.

A namespace name is unique in the cluster. A collection name is unique within its namespace. Both Acme and Northwind can therefore have a collection named `incident-logs`. The namespace in the request URL identifies which one you mean.

## Discover capabilities

Call [Info](/engine/reference/info) with any valid key. It reports the cluster name, major API version, supported URI schemes, Search modes, Query modes, and event types. A mode or URI scheme must be available on your cluster before you use it.

[Health](/engine/reference/health) checks liveness. [Ready](/engine/reference/ready) reports whether the cluster is ready to serve work. These two endpoints do not require a key. A readiness failure returns `503`.

## Names and identifiers

Create namespaces with a name such as `acme`. Names contain 1–63 lowercase letters, digits, underscores, or hyphens. The first character is a letter or digit. Names are immutable; `display_name` is a separate, editable label.

Engine also returns an immutable `ns_` ID. Namespace URL parameters accept either the name or the ID. Collection IDs start with `col_` and follow the same choice. IDs include a 26-character ULID suffix. Do not choose a name that matches its resource’s ID format.

## Tenant boundaries

A cluster key can manage every namespace. A namespace key is limited to one namespace. A collection key is limited to named collections in one namespace. Requests beyond the key’s resource boundary return `404 not_found`, even when the resource exists.

Namespace usage reports collection count, file count, and byte totals. Byte totals are decimal strings so large values retain precision. Your application can use usage to enforce its own product limits.

Follow [Isolate tenants and issue keys](/engine/guides/tenant-keys) for a provisioning flow.
## Sitemap

See the full [sitemap](/sitemap.md) for all pages.