Tenancy hierarchy
Cantora uses one fixed hierarchy: Organization → Project → Environment → Tenant → User. Resource URLs repeat the identifiers that establish their complete scope; the API never infers scope from a display name or an external provider payload.
| Resource | Purpose | Contains |
|---|---|---|
| Organization | Customer ownership, administration, and billing boundary | Projects and management identities |
| Project | One product built on Cantora | Agent Definitions, Agent Versions, and Environments |
| Environment | Either test or live, with separate runtime configuration and data | Agents, Agent Releases, Surface registrations, and Tenants |
| Tenant | Runtime and data-isolation boundary inside one Environment | Users and Tenant-scoped Product State |
| User | One human runtime identity on a Surface | User-scoped context and authority |
An Organization and a Tenant may represent the same real-world company, but they remain different resources. The Organization is the management boundary; the Tenant is the runtime isolation boundary.
Agent Configuration resources
Agent behavior moves through four resources. Publication and activation are separate operations, so creating a version does not silently change runtime traffic.
- An Agent Definition gives one logical Agent a stable Project-scoped identity.
- An Agent Version is an immutable snapshot of instructions, the exact model it runs on, Tools, required bindings, and finite execution budgets.
- An Agent binds the Agent Definition to one Environment as a runtime principal.
- An Agent Release is an append-only activation of one exact Agent Version for that Agent.
Test and Live can select the same immutable Agent Version, but each Environment has its own Agent, Connections, Surface registrations, Tenants, and release history. A release affects new work only; accepted Runs stay pinned to the version and release they started on.
Continue with the generated operations for Agent Definitions, Agent Versions, Agents, and Agent Releases.