Trillet AI logo

Delete Workspace

Delete a workspace you own, along with its call flows, agents, knowledge bases and phone numbers. Master workspaces and your only remaining workspace can't be deleted.

DELETEhttps://api.trillet.ai/v1/api/workspaces/{workspaceId}

Deleting a workspace also removes everything in it:

  • Phone numbers. Numbers from your plan's free allowance and numbers you brought yourself are released immediately and are not brought back by a restore. Paid numbers have their renewal cancelled and stay until the end of the period you've already paid for.
  • Call flows, agents and knowledge bases are deleted (soft-deleted, so a restore brings them back).
  • The workspace wallet is deleted with the workspace (also restorable).
  • External members lose their roles in the workspace, and their invitations are removed.

Anyone whose current workspace was this one is moved to the parent (master) workspace.

Path Parameters

workspaceIdstringrequired

The _id of the workspace to delete.

Headers

x-workspace-idstringrequired

A workspace where your role has the workspace:delete permission. The permission is checked against this header, not the path, so this is normally your master workspace.

Rules

  • You must be the owner of the workspace. Team members get 403.
  • The workspace can't be your master workspace.
  • It can't be your only workspace.

Response Fields

successboolean

true when the workspace was deleted.

Errors

StatusBodyWhen
403{"error": "Cannot delete your only workspace. You must have at least one workspace."}It's your only workspace (checked first)
403{"error": "Cannot delete the master workspace"}It's your master workspace
403{"error": "Only the workspace owner can delete the workspace"}You aren't the owner
403{"error": "Insufficient permissions", ...}Your role in the x-workspace-id workspace lacks workspace:delete
404{"error": "Workspace not found"}No workspace with that ID that you can see
500{"error": "..."}Unexpected server error

Restoring a deleted workspace

The owner can restore a deleted workspace within 30 days with POST /v1/api/workspaces/{workspaceId}/restore (no body, same x-workspace-id rule as delete). Its call flows, agents, knowledge bases and wallet come back, and paid numbers whose renewal was cancelled are renewed again where possible. The response is {"success": true, "workspace": {...}, "numbers": {"reinstated": 1, "failed": 0}}.

Restore errors carry a code: 403 NOT_OWNER, 400 MASTER_WORKSPACE, 409 ALREADY_ACTIVE, 410 RECOVERY_WINDOW_EXPIRED (with recoverableUntil), 423 WORKSPACE_CHANGE_IN_PROGRESS (retry shortly), and 404 if no deleted workspace with that ID exists. If restoring would take you over your plan's workspace limit, it returns 402 with requiresPayment: true.

{
  "success": true
}

Last updated on