API Reference

Delete Conversation

Overview

Permanently delete a single conversation and its related messages and membership records.

The success response reports how many conversations, messages, and members were removed so you can confirm cleanup in admin tools and audit logs.

When to use this endpoint?

Use Delete Conversation when:

An admin removes one conversation from the tenant workspace.
You need to clean up a specific thread and its messages permanently.
The UI offers a single-item delete action (not bulk selection).

To remove many conversations at once, use Conversations → Bulk Delete Conversations instead.

DELETE{baseUrl}/api/{apiVersion}/client/conversations/:conversationId

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Access Token from Login Client or Register Client.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Uses the {{clientId}} variable.

Path Parameters

Parameter	Example	Description
conversationId	string	Conversation _id (24-char Mongo ObjectId).

Success Response (HTTP 200 OK)

Deletion removes the conversation plus cascaded messages and members. Counts are returned in data.

json

{
  "success": true,
  "message": "Conversation deleted successfully",
  "data": {
    "conversationsDeleted": 1,
    "messagesDeleted": 42,
    "membersDeleted": 3
  },
  "error": null
}

Error Responses

HTTP 404 Not Found — Not found

json

{
  "success": false,
  "message": "Conversation not found",
  "data": null,
  "error": "Conversation not found"
}

Notes & Validation Rules

Conversation not found (HTTP 404 - Not found)

Common Errors

Delete fails when the conversation does not exist or the request is not authenticated for the tenant.

Code	Reason
400 Bad Request	`conversationId` is missing or not a valid ObjectId.
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	Conversation not found for the given `conversationId`.
500 Internal Server Error	An unexpected error occurred while deleting the conversation.

Best Practices

Treat delete as irreversible — confirm in the UI before calling the API.
Use the returned messagesDeleted and membersDeleted counts for audit or toast feedback.
Prefer Bulk Delete Conversations when removing multiple IDs in one request.
Refresh list views after a successful delete so removed threads disappear immediately.

Conversation removed

Return to Conversations → List Conversations to confirm the thread is gone, or continue cleanup with Bulk Delete Conversations.

API Reference

Delete Conversation

Overview

Permanently delete a single conversation and its related messages and membership records.

The success response reports how many conversations, messages, and members were removed so you can confirm cleanup in admin tools and audit logs.

When to use this endpoint?

Use Delete Conversation when:

An admin removes one conversation from the tenant workspace.
You need to clean up a specific thread and its messages permanently.
The UI offers a single-item delete action (not bulk selection).

To remove many conversations at once, use Conversations → Bulk Delete Conversations instead.

DELETE{baseUrl}/api/{apiVersion}/client/conversations/:conversationId

Authentication

Required (Bearer token)

Tenant-scoped

Yes (tenant DB — requires x-client-id)

Request Headers

Header	Value	Description
Authorization	Bearer <access_token>	Access Token from Login Client or Register Client.
is-tenant	true	Targets the tenant DB ("true", needs x-client-id).
x-client-id	{{clientId}}	Tenant (client) id. Uses the {{clientId}} variable.

Path Parameters

Parameter	Example	Description
conversationId	string	Conversation _id (24-char Mongo ObjectId).

Success Response (HTTP 200 OK)

Deletion removes the conversation plus cascaded messages and members. Counts are returned in data.

json

{
  "success": true,
  "message": "Conversation deleted successfully",
  "data": {
    "conversationsDeleted": 1,
    "messagesDeleted": 42,
    "membersDeleted": 3
  },
  "error": null
}

Error Responses

HTTP 404 Not Found — Not found

json

{
  "success": false,
  "message": "Conversation not found",
  "data": null,
  "error": "Conversation not found"
}

Notes & Validation Rules

Conversation not found (HTTP 404 - Not found)

Common Errors

Delete fails when the conversation does not exist or the request is not authenticated for the tenant.

Code	Reason
400 Bad Request	`conversationId` is missing or not a valid ObjectId.
401 Unauthorized	Access Token is missing, invalid, or expired.
404 Not Found	Conversation not found for the given `conversationId`.
500 Internal Server Error	An unexpected error occurred while deleting the conversation.

Best Practices

Treat delete as irreversible — confirm in the UI before calling the API.
Use the returned messagesDeleted and membersDeleted counts for audit or toast feedback.
Prefer Bulk Delete Conversations when removing multiple IDs in one request.
Refresh list views after a successful delete so removed threads disappear immediately.

Conversation removed

Return to Conversations → List Conversations to confirm the thread is gone, or continue cleanup with Bulk Delete Conversations.