# Delete a folder

**DELETE** `/api/folders/{id}`

Deletes a folder. What was in it moves up one level; nothing else is deleted.

Needs [an API token](https://docs.gorunner.io/api/authentication#scopes) with the **Write** permission for workflows (`workflow:write`).

## Parameters

### Path

- `id` · Required · UUID: The folder’s ID.

## What moves

In one step, the folders and workflows inside it move to the folder’s own parent, or to the top level if it had none. No workflow is deleted or left without a place. A folder whose name is taken in its new place is renamed `Name (2)`, `(3)` and so on.

## Responses

- 200 OK

  Deleted, and its contents moved up.

- 400 `VALIDATION_ERROR`

  The ID isn’t a UUID.

- 403 `FORBIDDEN`

  The token lacks the **Write** permission for workflows.

- 404 `NOT_FOUND`

  No folder with this ID in the workspace.

- 500 `INTERNAL_ERROR`

  Nothing was deleted. Try again.

Any call can also answer: [`401 UNAUTHORIZED`](https://docs.gorunner.io/errors#UNAUTHORIZED) · [`401 TOKEN_ENDED`](https://docs.gorunner.io/errors#TOKEN_ENDED) · [`403 TOKEN_SURFACE_OFF`](https://docs.gorunner.io/errors#TOKEN_SURFACE_OFF) · [`403 FEATURE_OFF`](https://docs.gorunner.io/errors#FEATURE_OFF) · [`403 EMBED_NOT_ALLOWED`](https://docs.gorunner.io/errors#EMBED_NOT_ALLOWED) · [`403 EMBED_NOT_AVAILABLE`](https://docs.gorunner.io/errors#EMBED_NOT_AVAILABLE) · [`403 ACCOUNT_SUSPENDED`](https://docs.gorunner.io/errors#ACCOUNT_SUSPENDED) · [`429 RATE_LIMITED`](https://docs.gorunner.io/errors#RATE_LIMITED) · [`503 BUSY`](https://docs.gorunner.io/errors#BUSY) · [`503 PAUSED`](https://docs.gorunner.io/errors#PAUSED) · [`503 SERVICE_UNAVAILABLE`](https://docs.gorunner.io/errors#SERVICE_UNAVAILABLE). See [Errors](https://docs.gorunner.io/api/errors#by-status).

Request

**curl**

```bash
GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Write for workflows
FOLDER_ID="your-folder-id"

curl -X DELETE "$GORUNNER/api/folders/$FOLDER_ID" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"
```

**JavaScript**

```js
const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const FOLDER_ID = process.env.FOLDER_ID;

const res = await fetch(
  `${GORUNNER}/api/folders/${FOLDER_ID}`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();
```

**Python**

```python
import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
FOLDER_ID = os.environ["FOLDER_ID"]

res = requests.delete(
    f"{GORUNNER}/api/folders/{FOLDER_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]
```

Response · 200 OK

```json
{
  "data": {
    "id": "7a2c9e41-5b3d-4f08-a6e1-2d9c4b7f0e13",
    "deleted": true
  }
}
```

**Every field**

It takes no body.

### Response · 200 OK

- `data` · object: Bare acknowledgement returned by folder update and delete. It does NOT contain the folder — re-list if you need the new state.
  - `id` · UUID: The folder the operation applied to.
  - `updated` · boolean: Always true; present on the update response only.
  - `deleted` · boolean: Always true; present on the delete response only.

Related: [List folders](https://docs.gorunner.io/api/folders/list-folders) · [Delete a workflow](https://docs.gorunner.io/api/workflows/delete-workflow)

Source: https://docs.gorunner.io/api/folders/delete-folder