Skip to main content
Deleting an AI assistant is a two-stage lifecycle. DELETE /v2/ai/assistants/{assistant_id} performs a soft delete by default: the assistant moves to the Recently Deleted list, where it stays restorable for 30 days and is then permanently deleted automatically. Pass hard_delete=true to skip the retention window and delete permanently in one request. The same lifecycle is available in the Mission Control Portal under AI, Storage and Compute > AI Assistants, in the Recently Deleted tab.

​
Soft delete

By default, DELETE /v2/ai/assistants/{assistant_id} soft-deletes the assistant:
  • The assistant no longer appears in the active assistant list.
  • Its versions and TeXML application are preserved, so the assistant can be restored intact.
  • The response carries deleted: true, object: "assistant.deleted", and the assistant’s id.
List the assistants in the retention window with GET /v2/ai/assistants/deleted (paginated with page[number] and page[size], up to 100 per page). Each entry carries deleted_at — when the assistant was soft-deleted — and permanently_deleted_at — the point after which it is erased automatically and can no longer be restored. Inspect a single entry with GET /v2/ai/assistants/{assistant_id}/deleted. Deletion fails with 400 if other assistants depend on the one being deleted:
  • Another assistant’s handoff tool points to it.
  • Another assistant’s conversation flow has an edge handing off to it.
Remove those references first; the error names the referencing assistants.

​
Restore

Restore a soft-deleted assistant with POST /v2/ai/assistants/{assistant_id}/restore. The assistant becomes active again with its versions and TeXML application as they were at deletion time — soft delete only marks the assistant deleted, so nothing else needs re-attaching. In the Portal, open the Recently Deleted tab and select Restore.

​
Retention and automatic permanent deletion

A soft-deleted assistant is kept for 30 days. permanently_deleted_at in the deleted-assistant listing is exactly deleted_at plus 30 days. After that point the assistant is permanently deleted automatically by a background job that runs every 6 hours, so the actual erasure can lag the 30-day mark by up to 6 hours. Once erased, an assistant cannot be restored.

​
Permanent deletion

Two ways to delete an assistant permanently:
  • Wait for the 30-day retention window to expire on a soft-deleted assistant.
  • Pass hard_delete=true to DELETE /v2/ai/assistants/{assistant_id} — this deletes permanently immediately, skipping the retention window. It works both on a soft-deleted assistant and on an active one.
A hard delete erases:
  • The assistant and all of its versions.
  • The assistant’s TeXML application — unless phone numbers are still assigned to it, in which case the TeXML application is kept (the assistant itself is still deleted).
A hard delete does not erase:
  • Conversations and messages the assistant took part in.
  • Call recordings.
  • Shared tools the assistant referenced — these live in the Tools Library and may be used by other assistants.
  • Knowledge-base files and their embeddings.
The dependency guards that block a soft delete also apply to a hard delete of an active assistant: a handoff tool or conversation-flow edge from another assistant blocks the request with 400 until the reference is removed. A soft-deleted assistant is exempt, so the automatic cleanup of expired assistants can always finish.

​
Deleting an assistant does not delete its shared tools

A shared tool in the Tools Library is not deleted when an assistant that references it is deleted — the tool stays available for other assistants. While an assistant is in Recently Deleted, it still counts as referencing its tools: a tool referenced only by trash-resident assistants cannot be deleted, because restoring the assistant would revive a dangling reference. The tool-delete error names the soft-deleted assistants blocking it. To free the tool, either:
  • Restore each referencing assistant, remove the tool from it, then delete the tool, or
  • Delete the referencing assistants permanently with hard_delete=true, then delete the tool.
See Tools Library for the shared-tool model.

​
Permanent-purge procedure

To permanently remove AI assistants while leaving telephony untouched — for example when retiring AI assets:
  1. List the assistants in the retention window: GET /v2/ai/assistants/deleted.
  2. For each assistant to purge, call DELETE /v2/ai/assistants/{assistant_id}?hard_delete=true.
  3. Verify the entry is gone: GET /v2/ai/assistants/deleted no longer lists it, and GET /v2/ai/assistants/{assistant_id} returns 404.
This erases the assistants and their versions and deletes their TeXML applications (unless numbers are still assigned). It leaves conversations, recordings, shared tools, and knowledge bases untouched. Phone numbers, SIP connections, Call Control applications, and messaging profiles are unaffected by assistant deletion and keep working.