directus/docs/reference/api/rest/folders.md

pageClass

pageClass
page-reference

Folders

Folders can be used to organize files within the platform. Folders are virtual, and aren't mirrored within the storage adapter.

toc

---

The Folder Object

id uuid
Primary key of the folder.

name string
Name of the folder.

parent many-to-one
Parent folder. Many-to-one to folders (recursive).

{
	"data": {
		"id": "fc02d733-95b8-4e27-bd4b-08a32cbe4e66",
		"name": "Test",
		"parent": null
	}
}

---

List Folders

List all folders that exist in Directus.

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit folder objects. If no items are available, data will be an empty array.

GET /folders

// Response

{
	"data": [
		{
			"id": "fc02d733-95b8-4e27-bd4b-08a32cbe4e66",
			"name": "Test",
			"parent": null
		},
		{...},
		{...}
	]
}

---

Retrieve a Folder

List all folders that exist in Directus.

Query Parameters

Supports all global query parameters.

Returns

Returns a folder object if a valid primary key was provided.

GET /folders/:id

// Response

{
	"data": {
		"id": "fc02d733-95b8-4e27-bd4b-08a32cbe4e66",
		"name": "Test",
		"parent": null
	}
}

---

Create a Folder

Create one or more new virtual folder(s).

Query Parameters

Supports all global query parameters.

Request Body

A partial folder object or an array of partial folder objects. name is required.

Returns

Returns the folder object of the folder that was created.

POST /folders

// Request

{
	"name": "Test"
}

// Response

{
	"data": {
		"id": "fc02d733-95b8-4e27-bd4b-08a32cbe4e66",
		"name": "Test",
		"parent": null
	}
}

---

Update a Folder

Update an existing folder.

Query Parameters

Supports all global query parameters.

Request Body

A partial folder object.

Returns

Returns the folder object of the folder that was updated.

PATCH /folders/:id

// Request

{
	"parent": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
}

// Response

{
	"data": {
		"id": "fc02d733-95b8-4e27-bd4b-08a32cbe4e66",
		"name": "Test",
		"parent": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
	}
}

---

Delete a Folder

Delete an existing folder.

::: tip Files

Any files in this folder will be moved to the root folder.

:::

Returns

Empty body.

DELETE /folders/:id

// Empty Response

---

Delete Multiple Folders

Delete multiple existing folders.

::: tip Files

Any files in these folders will be moved to the root folder.

:::

Request Body

An array of folder primary keys.

Returns

Empty body.

DELETE /folders

// Request
["d97c2e0e-293d-4eb5-9e1c-27d3460ad29d", "fc02d733-95b8-4e27-bd4b-08a32cbe4e66"]

// Empty Response