directus/docs/reference/system/folders.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Folders collection in Directus.	4 min read	page-reference

Folders

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

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.

Request

GET /folders

SEARCH /folders

POST /graphql/system

type Query {
	folders: directus_folders
}

import { createDirectus } from '@directus/sdk';
import { rest, readFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(readFolders(query));

Learn more about SEARCH ->

Query Parameters

Supports all global query parameters.

Response

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

Example

GET /folders

SEARCH /folders

POST /graphql/system

query {
	folders {
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readFolders({
		fields: ['*'],
	})
);

Retrieve a Folder

List an existing folder by primary key.

Request

GET /folders/:id

POST /graphql/system

type Query {
	folders_by_id(id: ID!): directus_folders
}

import { createDirectus } from '@directus/sdk';
import { rest, readFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(readFolder('folder_id', query));

Query Parameters

Supports all global query parameters.

Response

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

Example

GET /folders/fc02d733-95b8-4e27-bd4b-08a32cbe4e66

POST /graphql/system

query {
	folders_by_id(id: "fc02d733-95b8-4e27-bd4b-08a32cbe4e66") {
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readFolder('a141336b-398a-44d0-ad1b-4e31b09219a1', {
		fields: ['*'],
	})
);

Create a Folder

Create a new (virtual) folder.

Request

POST /folders

{
	"name": "value_1"
}

POST /graphql/system

type Mutation {
	create_folders_item(data: create_directus_folders_input): directus_folders
}

import { createDirectus } from '@directus/sdk';
import { rest, createFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFolder({
		name: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial folder object. name is required.

Response

Returns the folder object of the folder that was created.

Example

POST /folders

{
	"name": "Nature"
}

POST /graphql/system

mutation {
	create_folders_item(data: { name: "Nature" }) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFolder({
		name: 'banner images',
	})
);

Create Multiple Folders

Create multiple new (virtual) folders.

Request

POST /folders

[
	{
		"name": "value_1"
	},
	{
		"name": "value_2"
	}
]

POST /graphql/system

type Mutation {
	create_folders_items(data: [create_directus_folders_input]): [directus_folders]
}

import { createDirectus } from '@directus/sdk';
import { rest, createFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFolders([
		{
			name: 'value_1',
		},
		{
			name: 'value_2',
		},
	])
);

Query Parameters

Supports all global query parameters.

Request Body

An array of partial folder objects. name is required.

Response

Returns the folder object of the folder that was created.

Example

POST /folders

[
	{
		"name": "Nature"
	},
	{
		"name": "Cities"
	}
]

POST /graphql/system

mutation {
	create_folders_items(data: [{ name: "Nature" }, { name: "Cities" }]) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createFolders([
		{
			name: 'hero images',
		},
		{
			name: 'transcript pdfs',
		},
	])
);

Update a Folder

Update an existing folder.

Request

PATCH /folders/:id

{
	"folder_object_field": "value_1"
}

POST /graphql/system

type Mutation {
	update_folders_item(id: ID!, data: update_directus_folders_input): directus_folders
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFolder('folder_id', {
		field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial folder object.

Response

Returns the folder object of the folder that was updated.

Example

PATCH /folders/fac21847-d5ce-4e4b-a288-9abafbdfbc87

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

POST /graphql/system

mutation {
	update_folders_item(
		id: "fac21847-d5ce-4e4b-a288-9abafbdfbc87"
		data: { parent: "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d" }
	) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFolder('a3c77ec8-35f0-467b-9dc5-5195c4cfdae0', {
		parent: 'a151aa85-4784-44cb-8ee8-c568e45e00fd',
	})
);

Update Multiple Folders

Update multiple existing folders.

Request

PATCH /folders

{
	"keys": ["folder_1_key", "folder_2_key"],
	"data": {
		"folder_object_field": "value_1"
	}
}

POST /graphql/system

type Mutation {
	update_folders_items(ids: [ID!]!, data: update_directus_folders_input): [directus_folders]
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(updateFolders(['folder_1_id', 'folder_2_id'], { field: 'value' }));

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the folders you'd like to update.

data Required
Any of the folder object's properties.

Response

Returns the folder objects of the folders that were updated.

Example

PATCH /folders

{
	"keys": ["fac21847-d5ce-4e4b-a288-9abafbdfbc87", "a5bdb793-dd85-4ac9-882a-b42862092983"],
	"data": {
		"parent": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
	}
}

POST /graphql/system

mutation {
	update_folders_items(
		ids: ["fac21847-d5ce-4e4b-a288-9abafbdfbc87", "a5bdb793-dd85-4ac9-882a-b42862092983"]
		data: { parent: "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d" }
	) {
		id
		name
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateFolders(['a3c77ec8-35f0-467b-9dc5-5195c4cfdae0', '1d8428f9-c437-4d4e-b3df-d276c605f454'], {
		parent: 'a151aa85-4784-44cb-8ee8-c568e45e00fd',
	})
);

Delete a Folder

Delete an existing folder.

::: tip Files

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

:::

Request

DELETE /folders/:id

POST /graphql/system

type Mutation {
	delete_folders_item(id: ID!): delete_one
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteFolder('folder_id'));

Response

Empty body.

Example

DELETE /folders/a5bdb793-dd85-4ac9-882a-b42862092983

POST /graphql/system

mutation {
	delete_folders_item(id: "fac21847-d5ce-4e4b-a288-9abafbdfbc87") {
		id
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFolder } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteFolder('a3c77ec8-35f0-467b-9dc5-5195c4cfdae0'));

Delete Multiple Folders

Delete multiple existing folders.

::: tip Files

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

:::

Request

DELETE /folders

["folder_1_key", "folder_2_key"]

POST /graphql/system

type Mutation {
	delete_folders_items(ids: [ID!]!): delete_many
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteFolders(['folder_1_id', 'folder_2_id']));

Request Body

An array of folder primary keys.

Returns

Empty body.

Example

DELETE /folders

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

mutation {
	delete_folders_items(ids: ["fac21847-d5ce-4e4b-a288-9abafbdfbc87", "a5bdb793-dd85-4ac9-882a-b42862092983"]) {
		ids
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteFolders } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	deleteFolders(['1d8428f9-c437-4d4e-b3df-d276c605f454', 'a151aa85-4784-44cb-8ee8-c568e45e00f'])
);