> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete Conversation Records with the Retention Period API
[Back to API List](/ai-for-service/apis/automation/api-list)
Use this API to delete specific conversations by conversation IDs within the defined retention period or to delete all conversations associated with a specific channel user. It's a two-step process:
1. Initiate a deletion job.
2. Retrieve the deletion job status.
This API only initiates the deletion job. The actual deletion of conversation records is performed during off-peak hours.
## Initiate a Deletion Job for Specific Conversations
Use this API to delete specific conversation records by conversation IDs.
| Field | Value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Method** | POST |
| **Endpoint** | `https://{{host}}/api/public/bot/{{botId}}/conversations/delete` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token). |
| **API Scope** | App Builder: Delete Conversations; Admin Console: Not Applicable |
### Path Parameters
| Parameter | Required | Description |
| --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `host` | Required | Environment URL, for example, `https://platform.kore.ai`. |
| `botId` | Required | App ID or Stream ID. You can access it by navigating to **App Settings** → **App Profile** in the app. |
### Sample Request
```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/conversations/delete' \
--header 'auth: {{jwt_token}}' \
--header 'Content-Type: application/json' \
--data '{
"conversationIds": [
"69eb0c87ec444445976xxxxx",
"69eb0b5c7cd98618e06xxxxx"
]
}'
```
### Header Parameters
| Parameter | Required | Description |
| --------- | -------- | -------------------------------------------------------- |
| `auth` | Required | Environment URL, for example, `https://platform.kore.ai` |
| `botId` | Required | application/json;charset=UTF-8 |
### Request Parameters
| Parameter | Type | Required | Description |
| ----------------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `conversationIds` | array of strings | required | List of conversation IDs to delete. Max 100 items per request. Takes precedence over date parameters. |
### Sample Response
```json theme={null}
{
"status": "queued",
"jobId": "cdj-e8c0d360-6b5b-50ab-bda1-ae54b18xxxxx",
"message": "Deletion job queued successfully. The bot owner will be notified by email on completion.",
"submittedAt": "2026-05-08T06:22:56.097Z"
}
```
### Response Parameters
| Parameter | Type | Description |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status` | string | Indicates the current status of the deletion job request. A value of `queued` indicates that the job was successfully accepted and scheduled for processing. |
| `jobId` | string | Unique job identifier to check the job status. Included in change logs and in the bot owner's completion email for correlation. |
| `message` | string | Response message indicating the result of the request. |
| `submittedAt` | string (date-time) | UTC timestamp at which the request was received and queued |
## Initiate a Deletion Job to Delete a Channel User's Conversation Records
Use this API to delete all conversation records associated with a specific channel user within the specified date range and retention period.
| Field | Value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Method** | POST |
| **Endpoint** | `https://{{host}}/api/public/bot/{{botId}}/conversations/delete` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token). |
| **API Scope** | App Builder: Delete Conversations; Admin Console: Not Applicable |
### Path Parameters
| Parameter | Required | Description |
| --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `host` | Required | Environment URL, for example, `https://platform.kore.ai` |
| `botId` | Required | App ID or Stream ID. You can access it by navigating to **App Settings** → **App Profile** in the app. |
### Sample Request
```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/conversations/delete' \
--header 'auth: {{jwt_token}}' \
--header 'Content-Type: application/json' \
--data '{
"cId":"u-e64325ed-82dc-5dd4-88dd-54ac52exxxxx",
"startDate": "2026-05-04T00:00:00.000Z",
"endDate": "2026-05-04T23:59:59.999Z"
}'
```
### Header Parameters
| Header | Description | Required/Optional |
| -------------- | ------------------------------ | ----------------- |
| `auth` | JWT token for authentication. | required |
| `Content-Type` | application/json;charset=UTF-8 | required |
### Request Parameters
| Parameter | Type | Required | Description |
| ----------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cId` | string | Yes | A unique customer identifier whose conversation records must be deleted. |
| `startDate` | string (date) | No | Inclusive start of the deletion range. ISO 8601 format YYYY-MM-DD. Defaults to the user or bot creation date (whichever is later) when cId is used and this is omitted |
| `endDate` | string (date) | No | Inclusive end of the deletion range. ISO 8601 format YYYY-MM-DD. Must not be a future date. Defaults to the current date when omitted |
### Sample Response
```json theme={null}
{
"status": "queued",
"jobId": "cdj-1e905b0a-41be-5484-ac9b-3a31a41xxxxx",
"message": "Deletion job queued successfully. The bot owner will be notified by email on completion.",
"submittedAt": "2026-05-11T04:50:20.538Z"
}
```
### Response Parameters
| Parameter | Type | Description |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status` | string | Indicates the current status of the deletion job request. A value of `queued` indicates that the job was successfully accepted and scheduled for processing. |
| `jobId` | string | Unique job identifier to check the job status. Included in change logs and in the bot owner's completion email for correlation. |
| `message` | string | Response message indicating the result of the request. |
| `submittedAt` | string (date-time) | UTC timestamp at which the request was received and queued |
## Retrieve Deletion Job Status
Use this API to retrieve the status and execution summary of a deletion job.
| Field | Value |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Method** | GET |
| **Endpoint** | `https://{{host}}/api/public/bot/{{botId}}/conversations/delete/{{jobId}}` |
| **Content Type** | `application/json` |
| **Authorization** | `auth: {{JWT}}` See [How to generate the JWT Token](/ai-for-service/apis/automation/api-introduction#generating-the-jwt-token). |
| **API Scope** | App Builder: Delete Conversations; Admin Console: Not Applicable |
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `botId` | string | Yes | The Stream ID or App ID. You can access it from the bot's App Settings --> App Profile page. |
| `host` | string | Yes | The Environment URL. For example, `https://platform.kore.ai` |
| `jobId` | string | yes | The unique identifier of the job whose status needs to be retrieved. |
### Sample Request
```bash theme={null}
curl --location 'https://{{host}}/api/public/bot/{{botId}}/conversations/delete/{{jobId}}' \
--header 'auth: {{jwt_token}}' \
--data ''
```
### Sample Response
The response includes the deleted records with the status as queued. After the job is run successfully and the records are deleted, the status changes to completed.
**When a job is queued**
```json theme={null}
{
"jobId": "cdj-2e5c62ad-df3a-542b-a59e-c72768xxxxx",
"status": "queued",
"requestType": "cId",
"submittedAt": "2026-05-08T17:49:06.505Z",
"scheduledAt": "2026-05-08T18:00:00.185Z",
"startedAt": "2026-05-08T18:00:00.204Z",
"completedAt": "2026-05-08T20:01:12.618Z",
"result": {
"totalConversations": 3,
"processedCount": 3,
"deletedCount": 89,
"failedCount": 0,
"skippedCount": 0,
"retriesRemaining": 3
}
}
```
**When a job is completed**
```json theme={null}
{
"jobId": "cdj-2e5c62ad-df3a-542b-a59e-c72768bxxxxx",
"status": "completed",
"requestType": "cId",
"submittedAt": "2026-05-08T17:49:06.505Z",
"scheduledAt": "2026-05-08T18:00:00.185Z",
"startedAt": "2026-05-08T18:00:00.204Z",
"completedAt": "2026-05-08T20:01:12.618Z",
"result": {
"totalConversations": 3,
"processedCount": 3,
"deletedCount": 89,
"failedCount": 0,
"skippedCount": 0,
"retriesRemaining": 3
}
}
```
### Response Parameters
| Parameter | Description | Type | Example |
| --------------------------- | -------------------------------------------------------------- | --------------------------- | ------------------------------------------ |
| `jobId` | Unique identifier generated for the deletion job. | string | `cdj-31e88d3d-b687-5bb6-9eb4-4ee67f6xxxxx` |
| `status` | Current status of the deletion job. | string | completed |
| `requestType` | Type of deletion request submitted. | string | `cId` |
| `submittedAt` | Timestamp indicating when the job request was submitted. | string (ISO 8601 timestamp) | `2026-05-04T19:43:14.534Z` |
| `scheduledAt` | Timestamp indicating when the job was scheduled for execution. | string (ISO 8601 timestamp) | `2026-05-07T18:00:00.073Z` |
| `startedAt` | Timestamp indicating when job execution started. | string (ISO 8601 timestamp) | `2026-05-07T18:00:00.091Z` |
| `completedAt` | Timestamp indicating when the job execution completed. | string (ISO 8601 timestamp) | `2026-05-07T18:00:01.008Z` |
| `result` | Object containing the deletion job execution summary. | object | |
| `result.totalConversations` | Total number of conversations identified for processing. | integer | 0 |
| `result.processedCount` | Total number of conversations processed by the job. | integer | 0 |
| `result.deletedCount` | Total number of conversations successfully deleted. | integer | 0 |
| `result.failedCount` | Total number of conversations that failed deletion. | integer | 0 |
| `result.skippedCount` | Total number of conversations skipped during processing. | integer | 0 |
| `result.retriesRemaining` | Number of retry attempts remaining for failed deletions. | integer | 3 |