usecortex · prathamgarg911 · Feb 20, 2026 · Feb 20, 2026
diff --git a/.DS_Store b/.DS_Store
diff --git a/api-reference/endpoint/create-tenant.mdx b/api-reference/endpoint/create-tenant.mdx
@@ -1,11 +1,19 @@
 ---
 title: "Create Tenant"
-description: "Creating a tenant (space) where you can store your memories"
+description: "Creating a tenant (space) where you can store your memories."
 openapi: "POST /tenants/create"
 ---
 
+<Info>
+  **API user endpoint**: Dashboard (NextAuth) tenant creation is documented separately under Dashboard endpoints.
+</Info>
+
 If you pass `tenant_id` as a query parameter, that ID will be used. If not provided, the service generates a new `tenant_id` and returns it.
 
+<Note>
+  **After creating a tenant**: Poll **GET /tenants/infra/status?tenant_id=...** to verify provisioning is complete before starting ingestion. See [Monitor & infra status](/api-reference/endpoint/monitor-tenant#check-tenant-infra-status) for details.
+</Note>
+
 ### Examples
 
 <Tabs>

diff --git a/api-reference/endpoint/delete-tenant.mdx b/api-reference/endpoint/delete-tenant.mdx
@@ -1,7 +1,38 @@
 ---
-title: 'Delete Tenant'
-description: 'Deleting a tenant space where you can store your memories'
-openapi: 'DELETE /tenant/delete'
+title: "Delete Tenant"
+description: "Permanently delete a tenant. Irreversible."
+openapi: "DELETE /tenants/delete"
 ---
 
-# Coming Soon
+<Info>
+**This operation is irreversible.** After deletion, the tenant and all its data cannot be recovered.
+</Info>
+
+### Examples
+
+<Tabs>
+  <Tab title="API Request">
+    ```bash wrap
+    curl -X 'DELETE' \
+      'https://api.usecortex.ai/tenants/delete?tenant_id=tenant_1234' \
+      --header 'Authorization: Bearer YOUR_API_KEY'
+    ```
+  </Tab>
+  <Tab title="Python (Sync)">
+    ```python
+    # Async usage: use async_client and await
+    response = client.tenant.delete_tenant(tenant_id="tenant_1234")
+    ```
+  </Tab>
+</Tabs>
+
+### Query Parameters
+
+- **tenant_id**: Required string – Unique identifier for the tenant to delete.
+
+### Response
+
+- **tenant_id**: The tenant that was scheduled for deletion.
+- **tracking_id**: ID to track status of deletion job (endpoint coming soon)
+- **status**: e.g. `deletion_scheduled`.
+- **message**: Confirmation that cleanup is in progress.
diff --git a/api-reference/endpoint/list-sub-tenant-ids.mdx b/api-reference/endpoint/list-sub-tenant-ids.mdx
@@ -0,0 +1,45 @@
+---
+title: "List Sub-Tenant IDs"
+description: "Returns the list of unique sub_tenant_id values that have indexed data for the given tenant (context and memory collections)."
+openapi: "GET /tenants/sub_tenant_ids"
+---
+
+
+Returns the list of unique `sub_tenant_id` values that have indexed data for the given tenant. Data is read from both context and memory collections, so the list reflects all sub-tenants that have been used for ingestion.
+
+Use this to discover which sub-tenants exist under a tenant, for auditing, usage reporting, or building UIs that depend on the set of active sub-tenants.
+
+### Examples
+
+<Tabs>
+  <Tab title="API Request">
+    ```bash wrap
+    curl -X 'GET' \
+      'https://api.usecortex.ai/tenants/sub_tenant_ids?tenant_id=tenant_1234' \
+      --header 'Authorization: Bearer YOUR_API_KEY'
+    ```
+  </Tab>
+  <Tab title="Python (Sync)">
+    ```python
+    # Async: use async_client and await
+    response = client.tenant.get_sub_tenant_ids(tenant_id="tenant_1234")
+    sub_tenant_ids = response.sub_tenant_ids
+    ```
+  </Tab>
+</Tabs>
+
+### Query Parameters
+
+- **tenant_id**: Required string – Unique identifier for the tenant/organization.
+
+### Response
+
+- **sub_tenant_ids**: Array of unique sub-tenant IDs that have indexed data in the tenant's collections.
+- **message**: Summary message (e.g. "Successfully retrieved sub-tenant IDs").
+
+### Use cases
+
+- **Audit**: List all sub-tenants that hold data for a tenant.
+- **Monitoring**: See how many sub-tenants are actively used.
+- **Dynamic UI**: Adapt interfaces based on available sub-tenants.
+- **Bulk operations**: Operate across multiple sub-tenants by iterating over the returned IDs.
diff --git a/api-reference/endpoint/monitor-tenant.mdx b/api-reference/endpoint/monitor-tenant.mdx
@@ -1,9 +1,21 @@
 ---
-title: "Monitor Tenants"
-description: "Retrieve usage stats and monitor your tenants. Use this to check whether a tenant exists and view core metrics like total indexed objects. This helps you validate setup and monitor ingestion."
+title: "Monitor & infra status"
+description: "Tenant monitoring and status: usage stats (object counts, vector dimension) and deployment status for graph and vectorstore."
 openapi: "GET /tenants/monitor"
 ---
 
+
+This page documents two tenant endpoints that appear together under **Monitor & infra status**:
+
+1. **Monitor tenant** (`GET /tenants/monitor`) – tenant usage stats (object counts, vector dimension).
+2. **Check tenant infra status** (`GET /tenants/infra/status`) – infra deployment status (graph, vectorstore).
+
+---
+
+## Monitor tenant
+
+`GET /tenants/monitor` returns usage statistics for a tenant or sub-tenant: object count, vector dimension, and tenant identifier. Use it to check whether a tenant exists and to monitor ingestion.
+
 ### Examples
 
 <Tabs>
@@ -33,40 +45,64 @@ openapi: "GET /tenants/monitor"
   </Tab>
 </Tabs>
 
-Retrieve statistics for a specific tenant or sub-tenant to get insights into organizational data including object count, vector dimensions, and tenant information.
-
 ### Query Parameters
 
 - **tenant_id**: Required string - Primary organizational identifier (e.g., enterprise client, company) for multi-tenant data isolation
 - **sub_tenant_id**: Optional string - Secondary organizational identifier (e.g., department, team, project) within a tenant for hierarchical data organization; defaults to tenant_id if not provided
 
-### Multi-Tenant Context
-
-This API leverages Cortex's hierarchical tenant system where:
-
-- **Tenant Level**: Stats for an entire organization (e.g., "acme_corp")
-- **Sub-Tenant Level**: Stats for specific departments or teams within an organization (e.g., "engineering" within "acme_corp")
-- **Data Isolation**: All statistics are completely isolated per tenant/sub-tenant combination
-
 ### Response Details
 
 - **object_count**: Number of objects/embeddings stored for the tenant
 - **vector_dimension**: Dimension size of the embedding vectors for this tenant
 - **tenant_id**: The name/identifier of the tenant
 
-## Use Cases
-
-This API is useful for:
+### Use cases
 
 - **Monitoring**: Track the number of embeddings stored for a tenant or department
 - **Validation**: Verify vector dimensions before uploading new embeddings to ensure compatibility
 - **Analytics**: Generate usage reports and statistics for billing, compliance, or optimization
-- **Capacity Planning**: Understand storage requirements and usage patterns across organizations
-- **Multi-Tenant Management**: Monitor data distribution across enterprise clients and their departments
-- **Department Insights**: Compare usage patterns between different teams within the same organization
+- **Capacity planning**: Understand storage requirements and usage patterns across organizations
+- **Multi-tenant management**: Monitor data distribution across enterprise clients and their departments
+
+---
+
+## Check tenant infra status
+
+`GET /tenants/infra/status` returns deployment status for the tenant’s infrastructure: **graph** and **vectorstore**. Use it to verify that tenant provisioning has completed before relying on the tenant.
+
+### Examples
+
+<Tabs>
+  <Tab title="API Request">
+    ```bash wrap
+    curl -X 'GET' \
+      'https://api.usecortex.ai/tenants/infra/status?tenant_id=tenant_1234' \
+      --header 'Authorization: Bearer YOUR_API_KEY'
+    ```
+  </Tab>
+  <Tab title="Python (Sync)">
+    ```python
+    # Async: use async_client and await
+    status = client.tenant.get_infra_status(tenant_id="tenant_1234")
+    # status.infra.graph_status, .vectorstore_status
+    ```
+  </Tab>
+</Tabs>
+
+### Query Parameters
+
+- **tenant_id**: Required string – Unique identifier for the tenant/organization.
+
+### Response
+
+- **tenant_id**: The tenant that was queried (when querying a specific tenant).
+- **org_id**: Organization identifier.
+- **infra**: Object with:
+  - **graph_status**: Boolean – whether the graph is deployed/ready.
+  - **vectorstore_status**: Array of two booleans – vectorstore status (e.g. context and memory).
+- **message**: Summary message (e.g. "Deployed infrastructure status").
 
-### Example Scenarios
+### When to use
 
-- **Enterprise Dashboard**: `tenant_id="acme_corp"` to see total company usage
-- **Department Analytics**: `tenant_id="acme_corp", sub_tenant_id="engineering"` for team-specific stats
-- **Client Reporting**: Generate individual reports for each enterprise client in your B2B platform
+- After **creating a tenant**: poll `GET /tenants/infra/status?tenant_id=...` until all relevant statuses are ready before starting ingestion.
+- After provisioning: confirm the tenant’s infra is fully deployed and in sync.