DELETE
Delete a directory (folder)
Request · Response · Guide: Folders
Files are NOT deleted. Each file is detached from the deleted directories and stays in the workspace and in any other directory it belongs to. To delete files, use DELETE /v1/files.Path Parameters:
  • directoryId (required): The directory to delete. Any depth is accepted — root, subfolder, or deeper.
Response:
  • directoryId: the directory you asked to delete
  • deletedDirectoryIds: every directory removed, the target first and then its subfolders
  • failedDirectoryIds: empty on a complete delete
Notes:
  • The delete is not reversible through the API.
  • A directory that has a workflow, contains one at any depth, or is the immediate subfolder of one, is rejected with a 422. Tearing a workflow down is not supported yet.
  • The Reference Hub is platform storage and cannot be deleted.
  • At most 1000 directories (the target plus its subfolders) are deleted in one request. A bigger tree is rejected with a 422 before anything is deleted; delete its deeper subfolders first.
  • A folder in the tree that holds a workflow result file is rejected with a 422 naming the folder ids, before anything is deleted. Remove or move those files first.
  • If a directory fails to delete part-way the response is still a 200, with the failures in failedDirectoryIds and everything already gone in deletedDirectoryIds. The delete stops there, so the target and anything above the failure are still present, and nothing is rolled back. Retry the same call to finish — a partial result is never cached, so retrying under the same Idempotency-Key re-runs the delete rather than replaying the partial response.
  • If nothing could be deleted at all the response is a 500, not a 200: no directory changed, and the same Idempotency-Key stays usable for the retry.
  • A second call for the same id is a 404, since the directory no longer exists.

Authorizations

​
x-api-key
string
header
required

API key for authentication

Headers

​
Idempotency-Key
string

Optional opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true.

Path Parameters

​
directoryId
string
required

Response

The delete ran. failedDirectoryIds is empty when the whole tree went; when it is not, deletedDirectoryIds is exactly what was removed before the delete stopped.

​
directoryId
string
required

The directory that was deleted, in canonical lowercase form.

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

​
deletedDirectoryIds
string[]
required

Every directory removed by this request: the target first, then its subfolders at any depth.

Example:
​
failedDirectoryIds
string[]
required

Directories that failed to delete. Empty on a complete delete. When it is not empty the delete stopped there, so the target and any directory above the failure are still present and deletedDirectoryIds is exactly what is already gone — nothing is rolled back. Retry the same call to finish.

Example: