13 KiB
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
If using SEARCH you can provide a query object as the body of your request.
POST /graphql/system
type Query {
folders: directus_folders
}
import { createDirectus, rest, readFolders } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readFolders(query_object));
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, rest, readFolders } from '@directus/sdk';
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, rest, readFolder } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readFolder(folder_id, query_object));
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, rest, readFolder } from '@directus/sdk';
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
Provide a folder object as the body of your request.
POST /graphql/system
type Mutation {
create_folders_item(data: create_directus_folders_input): directus_folders
}
import { createDirectus, rest, createFolder } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createFolder(folder_object));
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, rest, createFolder } from '@directus/sdk';
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
Provide an array of folder object as the body of your request.
POST /graphql/system
type Mutation {
create_folders_items(data: [create_directus_folders_input]): [directus_folders]
}
import { createDirectus, rest, createFolders } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createFolders(folder_object_array));
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, rest, createFolders } from '@directus/sdk';
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
Provide a partial folder object as the body of your request.
POST /graphql/system
type Mutation {
update_folders_item(id: ID!, data: update_directus_folders_input): directus_folders
}
import { createDirectus, rest, updateFolder } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateFolder(folder_id, partial_folder_object));
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, rest, updateFolder } from '@directus/sdk';
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_id_array,
"data": partial_folder_object
}
POST /graphql/system
type Mutation {
update_folders_items(ids: [ID!]!, data: update_directus_folders_input): [directus_folders]
}
import { createDirectus, rest, updateFolders } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateFolders(folder_id_array, partial_folder_object));
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, rest, updateFolders } from '@directus/sdk';
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, rest, deleteFolder } from '@directus/sdk';
const client = createDirectus('directus_project_url').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, rest, deleteFolder } from '@directus/sdk';
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
Provide an array of item IDs as your request body.
POST /graphql/system
type Mutation {
delete_folders_items(ids: [ID!]!): delete_many
}
import { createDirectus, rest, deleteFolders } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteFolders(folder_id_array));
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, rest, deleteFolders } from '@directus/sdk';
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'])
);