60df20d780
* Simplified generics and imports for items page snippets * Simplified generics and imports for files page snippets * Fixing simplified generic snippets in items page * Simplified generics and imports for activity page snippets * Simplified generics and imports for collections page snippets * Simplified generics and imports for dashboards page snippets * Simplified generics and imports for extensions page snippets * Simplified generics and imports for fields page snippets * Simplified generics and imports for flows page snippets * Simplified generics and imports for folders page snippets * Simplified generics and imports for notifications page snippets * Simplified generics and imports for operations page snippets * Simplified generics and imports for panels page snippets * Simplified generics and imports for permissions page snippets * Simplified generics and imports for presets page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for revisions page snippets * Simplified generics and imports for roles page snippets * Consolidated imports for schema page snippets * Simplified generics and imports for server page snippets * Simplified generics and imports for settings page snippets * Fixed mixed up snippets and simplified generics and imports for shares page snippets * Simplified generics and imports for translation page snippets * Fixed mixed up snippets and simplified generics and imports for user page snippets * Simplified generics and imports fo uutilitie pages snippets * Simplified generics and imports for webhook pages snippets * Simplified generics and imports for authentication pages snippets * Consolidated imports for query pages sdk snippets * Format files * Update lockfile * Fix spelling * Format snippets * Aling `result` const * Small clean-ups - Align `SEARCH` snippets, move "Learn more..." next to other hint - ids -> IDs - Other alignments --------- Co-authored-by: Bevis Halsey-Perry <hi@be7.is> Co-authored-by: Pascal Jufer <pascal-jufer@bluewin.ch>
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'])
);