Skip to content
Return to top
On this page

# 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).

json

    {
    	"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.

### REST API #

    GET /folders
    SEARCH /folders

Learn more about SEARCH ->

### GraphQL #

    POST /graphql/system

graphql

    type Query {
    	folders: directus_folders
    }

##### Example #

graphql

    query {
    	folders {
    		name
    	}
    }

## 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.

### REST API #

    GET /folders/:id

##### Example #

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

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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

## Create a Folder #

Create a new (virtual) folder.

### Query Parameters #

Supports all global query parameters.

### Request Body #

A partial folder object. `name` is required.

### Returns #

Returns the folder object of the folder that was created.

### REST API #

    POST /folders

##### Example #

json

    // POST /folders

    {
    	"name": "Nature"
    }

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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

## Create Multiple Folders #

Create multiple new (virtual) folders.

### Query Parameters #

Supports all global query parameters.

### Request Body #

An array of partial folder objects. `name` is required.

### Returns #

Returns the folder object of the folder that was created.

### REST API #

    POST /folders

##### Example #

json

    // POST /folders

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

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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

## 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.

### REST API #

    PATCH /folders/:id

##### Example #

json

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

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

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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

## Update Multiple Folders #

Update multiple existing folders.

### 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.

### Returns #

Returns the folder objects of the folders that were updated.

### REST API #

    PATCH /folders

##### Example #

json

    // PATCH /folders

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

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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

## Delete a Folder #

Delete an existing folder.

Files

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

### Returns #

Empty body.

### REST API #

    DELETE /folders/:id

##### Example #

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

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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

## Delete Multiple Folders #

Delete multiple existing folders.

Files

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

### Request Body #

An array of folder primary keys.

### Returns #

Empty body.

### REST API #

    DELETE /folders

##### Example #

json

    // DELETE /folders

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

### GraphQL #

    POST /graphql/system

graphql

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

##### Example #

graphql

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