---
updatedAt: 2026-09-02T17:35:26.000Z
agentTools:
  projectIndex: https://docs.go.v7labs.com/llms.txt
---

# Delete folder

Deletes a folder.
By default, will only delete empty folders.
If recursive=true, will delete the folder and all its contents (subfolders and projects).
  Recursive deletion is asynchronous which means that while all relevant children will become inaccessible immediately,
  only the parent folder will emit removal event. All clients need to assume all children are deleted based on that
  top level notification.
If recursive=false, will only delete the folder if it is empty, erroring otherwise.


# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "Common.APIErrorDetails": {
        "description": "Additional structured error context. Shape varies by error code.\n\n- For conflict errors: contains a `conflicts` array with conflicting resources\n- For other errors: may contain arbitrary error-specific context",
        "nullable": true,
        "oneOf": [
          {
            "$ref": "#/components/schemas/Common.ConflictErrorDetails"
          },
          {
            "additionalProperties": true,
            "description": "Generic error details for non-conflict errors",
            "type": "object",
            "x-struct": null,
            "x-validate": null
          }
        ],
        "title": "Common.APIErrorDetails",
        "x-struct": "Elixir.AgiDbWeb.Schemas.Common.APIErrorDetails",
        "x-validate": null
      },
      "Folders.Recursive": {
        "description": "Whether to recursively delete all nested folders and projects",
        "example": true,
        "title": "Folders.Recursive",
        "type": "boolean",
        "x-struct": "Elixir.AgiDbWeb.Schemas.Folders.Recursive",
        "x-validate": null
      },
      "Common.ConflictErrorDetails": {
        "additionalProperties": false,
        "description": "Details for conflict errors",
        "properties": {
          "conflicts": {
            "description": "List of conflicting resources",
            "items": {
              "additionalProperties": true,
              "type": "object",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "conflicts"
        ],
        "title": "Common.ConflictErrorDetails",
        "type": "object",
        "x-struct": "Elixir.AgiDbWeb.Schemas.Common.ConflictErrorDetails",
        "x-validate": null
      },
      "Common.UUID": {
        "example": "e23ff3f3-8f77-4e78-9e81-fdb25abfb781",
        "format": "uuid",
        "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
        "title": "Common.UUID",
        "type": "string",
        "x-struct": null,
        "x-validate": null
      },
      "Common.APIError": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "example": "bad_request",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          },
          "details": {
            "$ref": "#/components/schemas/Common.APIErrorDetails"
          },
          "message": {
            "example": "Bad Request",
            "type": "string",
            "x-struct": null,
            "x-validate": null
          }
        },
        "required": [
          "code",
          "message"
        ],
        "title": "Common.APIError",
        "type": "object",
        "x-struct": "Elixir.AgiDbWeb.Schemas.Common.APIError",
        "x-validate": null
      },
      "Common.DeleteResponse": {
        "additionalProperties": false,
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Common.UUID"
          }
        },
        "required": [
          "id"
        ],
        "title": "Common.DeleteResponse",
        "type": "object",
        "x-struct": "Elixir.AgiDbWeb.Schemas.Common.DeleteResponse",
        "x-validate": null
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "in": "header",
        "name": "X-API-KEY",
        "type": "apiKey"
      },
      "BearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "V7 Go API",
    "version": "0.1.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/api/workspaces/{workspace_id}/folders/{folder_id}": {
      "delete": {
        "callbacks": {},
        "description": "Deletes a folder.\nBy default, will only delete empty folders.\nIf recursive=true, will delete the folder and all its contents (subfolders and projects).\n  Recursive deletion is asynchronous which means that while all relevant children will become inaccessible immediately,\n  only the parent folder will emit removal event. All clients need to assume all children are deleted based on that\n  top level notification.\nIf recursive=false, will only delete the folder if it is empty, erroring otherwise.\n",
        "operationId": "folder-delete",
        "parameters": [
          {
            "description": "",
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Common.UUID"
            }
          },
          {
            "description": "",
            "in": "path",
            "name": "folder_id",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Common.UUID"
            }
          },
          {
            "description": "Whether to recursively delete all nested folders and projects",
            "in": "query",
            "name": "recursive",
            "required": false,
            "schema": {
              "$ref": "#/components/schemas/Folders.Recursive"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.DeleteResponse"
                }
              }
            },
            "description": "Common.DeleteResponse"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Common.APIError"
                }
              }
            },
            "description": "Common.APIError"
          }
        },
        "summary": "Delete folder",
        "tags": [
          "Folders"
        ]
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    },
    {
      "ApiKeyAuth": []
    }
  ],
  "servers": [
    {
      "description": "EU",
      "url": "https://go.v7labs.com",
      "variables": {}
    },
    {
      "description": "US",
      "url": "https://go.us.v7labs.com",
      "variables": {}
    },
    {
      "description": "UAE",
      "url": "https://go.uae.v7labs.com",
      "variables": {}
    }
  ]
}
```