Skip to main content
DELETE
/
tenant
/
delete_sub_tenant
Delete Sub Tenant
curl --request DELETE \
  --url https://api.usecortex.ai/tenant/delete_sub_tenant \
  --header 'Authorization: Bearer <token>'
{
  "status": "success",
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "success": true,
  "message": "Sub-tenant deleted successfully"
}
Hit the Try it button to try this API now in our playground. It’s the best way to check the full request and response in one place, customize your parameters, and generate ready-to-use code snippets.

​
Sample Request

curl --request DELETE \
  --url 'https://api.usecortex.ai/tenant/delete_sub_tenant?tenant_id=tenant_1234&sub_tenant_id=sub_tenant_4567' \
  --header 'Authorization: Bearer YOUR_API_KEY'
Delete a specific sub-tenant from a given tenant after validating it’s not the primary/default sub-tenant.
Important: You cannot delete the default sub-tenant. The default sub-tenant is automatically created when a tenant is created and serves as the organization-wide workspace. Attempting to delete it will result in a 400 Bad Request error.

​
Understanding Sub-Tenant Deletion

​
What Gets Deleted

When you delete a sub-tenant, the following occurs:
  • All Data Removal: All documents, embeddings, and metadata associated with the sub-tenant are permanently deleted
  • Complete Cleanup: The sub-tenant ID is removed from the tenant’s sub-tenant list
  • Irreversible Action: This operation cannot be undone - all data is permanently lost

​
What Cannot Be Deleted

  • Default Sub-Tenant: The automatically created default sub-tenant cannot be deleted
  • Primary Tenant: You cannot delete the main tenant itself using this API
Default Sub-Tenant Protection: Cortex automatically protects the default sub-tenant from deletion to ensure your organization always has a primary workspace. If you need to clean up the default sub-tenant, you would need to delete and recreate the entire tenant.

​
Query Parameters

  • tenant_id: Required string - The primary tenant identifier (e.g., your organization ID)
  • sub_tenant_id: Required string - The sub-tenant identifier to delete (e.g., department or team name)

​
Use Cases

​
Department Restructuring

  • Team Consolidation: Merge departments by deleting unused sub-tenants
  • Organizational Changes: Remove sub-tenants for departments that no longer exist
  • Cleanup: Remove test or temporary sub-tenants created during development

​
Data Management

  • Compliance: Remove sub-tenants containing sensitive data that’s no longer needed
  • Storage Optimization: Delete sub-tenants with outdated or irrelevant content
  • Privacy: Remove sub-tenants for users who have left the organization

​
Application Lifecycle

  • Project Cleanup: Remove sub-tenants for completed projects
  • Client Management: Delete sub-tenants for clients who have ended their contracts
  • Testing: Clean up test sub-tenants after development phases

​
Example Requests

​
Delete a Department Sub-Tenant

DELETE /delete_sub_tenant?tenant_id=acme_corp&sub_tenant_id=engineering

​
Delete a User Sub-Tenant (B2C)

DELETE /delete_sub_tenant?tenant_id=my_app&sub_tenant_id=user_12345

​
Delete a Project Sub-Tenant

DELETE /delete_sub_tenant?tenant_id=consulting_firm&sub_tenant_id=project_alpha

​
Sample Response

{
  "status": "success",
  "tenant_id": "acme_corp",
  "sub_tenant_id": "engineering",
  "message": "Sub-tenant 'engineering' deleted successfully from tenant 'acme_corp'"
}

​
Error Responses

All endpoints return consistent error responses following the standard format. For detailed error information, see our Error Responses documentation.

​
Best Practices

​
Before Deletion

  1. Verify Sub-Tenant: Use the List Sub-Tenant IDs endpoint to confirm the sub-tenant exists
  2. Backup Important Data: Export any critical data before deletion
  3. Check Dependencies: Ensure no active integrations depend on the sub-tenant

​
After Deletion

  1. Update Applications: Remove references to the deleted sub-tenant from your applications
  2. Notify Users: Inform relevant users that the sub-tenant workspace is no longer available
  3. Update Documentation: Remove the sub-tenant from any internal documentation

​
Safety Measures

  • Test in Development: Always test sub-tenant deletion in a development environment first
  • Gradual Rollout: Consider a phased approach for large-scale sub-tenant cleanup
  • Audit Trail: Keep records of which sub-tenants were deleted and when
Recovery: Once a sub-tenant is deleted, it cannot be recovered. The sub-tenant ID can be reused by creating new content with the same ID, but all previous data will be lost.
Impact on Active Users: Ensure no users are actively working with data in the sub-tenant before deletion, as this will result in immediate data loss and potential application errors.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
tenant_id
string
required
Example:

"tenant_1234"

​
sub_tenant_id
string
required
Example:

"sub_tenant_4567"

Response

Successful Response

​
status
string
required

The status of the deletion operation.

Example:

"success"

​
tenant_id
string
required

The tenant ID from which the sub-tenant was deleted.

Example:

"tenant_1234"

​
sub_tenant_id
string
required

The ID of the sub-tenant that was deleted.

Example:

"sub_tenant_4567"

​
success
boolean
default:true

Indicates whether the sub-tenant deletion was successful.

Example:

true

​
message
string
default:Sub-tenant deleted successfully

Response message describing the operation result.

⌘I