Clusters and namespaces
AI DraftIsolate tenants within a cluster and identify their resources.
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
Cluster
graphon.example.com
Namespace
acme
Collection
incident-logs
File
/incidents/checkout.txt
File
/incidents/payment-errors.json
File
/incidents/latency-chart.png
File
/incidents/checkout-review.mp4
Collection
policies
File
/policies/employee-handbook.pdf
File
/policies/data-retention.md
File
/policies/access-control.pdf
File
/policies/escalation-flow.png
Namespace
northwind
Collection
research
File
/research/customer-interview.mp3
File
/research/survey-results.json
File
/research/market-analysis.pdf
File
/research/findings.md
Collection
reports
File
/reports/2026/q1-summary.pdf
File
/reports/2026/q2-summary.pdf
File
/reports/2026/revenue.csv
File
/reports/2026/forecast.xlsx
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 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 checks liveness. 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 for a provisioning flow.