Tenants on the cloud

Your account is a scope subtree of its own, org:acct_<id> (your dashboard shows the id). Everything your token writes or reads lies under it, and nothing outside it is reachable: another account's memories answer 403 POLICY_DENIED, whatever scope you send.

A tenant is a scope one level under your account. Use one per application, team or end customer whose memories must stay apart:

org:acct_42                      your account (the plan applies here)
├── org:acct_42/user:acct_42     your first tenant: where the quickstart writes
├── org:acct_42/app:support      a support assistant
├── org:acct_42/app:sales        a sales copilot
└── org:acct_42/user:cust_981    one of your own customers

Scope segments are type:id pairs (Scopes); the types an account can create are user, agent, app, team, project and ws. A tenant is created by the first write to it, and each plan allows a number of them (Plans and limits): past it, the first write to a new tenant answers 402 PLAN_LIMIT_REACHED with limit: "tenants". Scopes deeper inside a tenant (org:acct_42/app:support/user:alice) don't count as tenants.

Keeping tenants apart

A recall reads the scope you send (views decide whether it includes the scope's ancestors or descendants). So a recall in org:acct_42/app:support never returns what org:acct_42/app:sales stored. Your account token can read every tenant; when you build on top of CortexDB for your own customers, send each customer's requests with that customer's tenant scope.

Reading several on purpose: extra_scopes

To answer from a tenant plus shared knowledge (for example an app's own memories and a shared app:handbook), list up to 8 more scopes of your account in extra_scopes. They are read in the same ranked pass, and each context_block line from one of them carries its last segment as a tag:

curl -sS -X POST 'https://api.cortexdb.ai/v1/recall' \
  -H "Authorization: Bearer $CORTEXDB_TOKEN" -H "X-Cortex-Actor: $CORTEXDB_ACTOR" \
  -H 'Content-Type: application/json' \
  -d '{"scope":"org:acct_42/app:support","extra_scopes":["org:acct_42/app:handbook"],"query":"refund policy"}'

Each extra scope must lie in your account; one outside it, or more than 8, answers 422 INVALID_EXTRA_SCOPES. Details: POST /v1/recall.

Usage per tenant

GET /v1/plan reports your whole account. GET /v1/usage?scope= reports one scope: the memories stored under it (storage) and, for your account, its reads and writes (Plans and usage).