Delete one of your assistant conversations
The assistant.conversations.delete operation: DELETE /api/v1/assistant/conversations/{id} in the REST API and the assistant_conversations_delete tool in the MCP server.
/api/v1/assistant/conversations/{id}Deletes one of your own assistant conversations and all of its messages, at once and for good. Changes the
assistant made for you stay, and so do their audit log entries (via: assistant, with the conversation's ID).
Who can call it: the conversation's owner, signed in. Anyone else gets conversation_not_found.
At a glance
- REST:
DELETE /api/v1/assistant/conversations/{id} - MCP tool:
assistant_conversations_delete - Operation ID:
assistant.conversations.delete - Scope: Platform
- Permission:
account:write - Risk tier:
write - Dry run: Supported (send
Ownrecord-Dry-Run: true) - Idempotency:
Idempotency-Keyoptional - Modes: Test and live
- Authentication: API key with the
account:writescope - Since: M11
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | aconv_… ID | The conversation (aconv_…). |
Body
This operation takes no body.
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | aconv_… ID | |
object | "assistant_conversation" | |
deleted | true | |
messagesDeleted | integer (at least 0) |
Examples
Delete a conversation
DELETE /api/v1/assistant/conversations/aconv_01jbz3k6q2e8w1m0v9r7t5y4x3
Authorization: Bearer or_test_…
Response (200):
{
"id": "aconv_01jbz3k6q2e8w1m0v9r7t5y4x3",
"object": "assistant_conversation",
"deleted": true,
"messagesDeleted": 2
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | The ID isn't an assistant conversation ID. | Fix the fields listed in details.issues and send the request again. |
conversation_not_found | 404 | No such conversation of yours (or it was already deleted). | Start a new conversation. Conversations are deleted after the organization's retention period, and only their owner can open them. |
version_conflict | 409 | The conversation got a new message at the same time; retry. | Fetch the object again and retry the change. |
permission_denied | 403 | The caller isn't a signed-in person (an API key or OAuth token). | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.