mirror of
https://github.com/directus/directus.git
synced 2026-04-25 03:00:53 -04:00
783 lines
13 KiB
Markdown
783 lines
13 KiB
Markdown
---
|
||
description: REST and GraphQL API documentation on the Folders collection in Directus.
|
||
readTime: 4 min read
|
||
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.
|
||
|
||
## 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.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /folders`
|
||
|
||
`SEARCH /folders`
|
||
|
||
If using SEARCH you can provide a [query object](/reference/query) as the body of your request.
|
||
|
||
[Learn more about SEARCH ->](/reference/introduction#search-http-method)
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Query {
|
||
folders: directus_folders
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, readFolders } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(readFolders(query_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
### Response
|
||
|
||
An array of up to [limit](/reference/query#limit) [folder objects](#the-folder-object). If no items are available, data
|
||
will be an empty array.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /folders`
|
||
|
||
`SEARCH /folders`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
query {
|
||
folders {
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, readFolders } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
readFolders({
|
||
fields: ['*'],
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Retrieve a Folder
|
||
|
||
List an existing folder by primary key.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /folders/:id`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Query {
|
||
folders_by_id(id: ID!): directus_folders
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
### Response
|
||
|
||
Returns a [folder object](#the-folder-object) if a valid primary key was provided.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /folders/fc02d733-95b8-4e27-bd4b-08a32cbe4e66`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
query {
|
||
folders_by_id(id: "fc02d733-95b8-4e27-bd4b-08a32cbe4e66") {
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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: ['*'],
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Create a Folder
|
||
|
||
Create a new (virtual) folder.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /folders`
|
||
|
||
Provide a [folder object](#the-folder-object) as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
create_folders_item(data: create_directus_folders_input): directus_folders
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, createFolder } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(createFolder(folder_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
A partial [folder object](#the-folder-object). `name` is required.
|
||
|
||
### Response
|
||
|
||
Returns the [folder object](#the-folder-object) of the folder that was created.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /folders`
|
||
|
||
```json
|
||
{
|
||
"name": "Nature"
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
create_folders_item(data: { name: "Nature" }) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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',
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Create Multiple Folders
|
||
|
||
Create multiple new (virtual) folders.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /folders`
|
||
|
||
Provide an array of [folder object](#the-folder-object) as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
create_folders_items(data: [create_directus_folders_input]): [directus_folders]
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, createFolders } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(createFolders(folder_object_array));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
An array of partial [folder objects](#the-folder-object). `name` is required.
|
||
|
||
### Response
|
||
|
||
Returns the [folder object](#the-folder-object) of the folder that was created.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /folders`
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "Nature"
|
||
},
|
||
{
|
||
"name": "Cities"
|
||
}
|
||
]
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
create_folders_items(data: [{ name: "Nature" }, { name: "Cities" }]) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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',
|
||
},
|
||
])
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Update a Folder
|
||
|
||
Update an existing folder.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /folders/:id`
|
||
|
||
Provide a partial [folder object](#the-folder-object) as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
update_folders_item(id: ID!, data: update_directus_folders_input): directus_folders
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
A partial [folder object](#the-folder-object).
|
||
|
||
### Response
|
||
|
||
Returns the [folder object](#the-folder-object) of the folder that was updated.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /folders/fac21847-d5ce-4e4b-a288-9abafbdfbc87`
|
||
|
||
```json
|
||
{
|
||
"parent": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
update_folders_item(
|
||
id: "fac21847-d5ce-4e4b-a288-9abafbdfbc87"
|
||
data: { parent: "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d" }
|
||
) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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',
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Update Multiple Folders
|
||
|
||
Update multiple existing folders.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /folders`
|
||
|
||
```json
|
||
{
|
||
"keys": folder_id_array,
|
||
"data": partial_folder_object
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
update_folders_items(ids: [ID!]!, data: update_directus_folders_input): [directus_folders]
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
`keys` **Required**\
|
||
Array of primary keys of the folders you'd like to update.
|
||
|
||
`data` **Required**\
|
||
Any of [the folder object](#the-folder-object)'s properties.
|
||
|
||
### Response
|
||
|
||
Returns the [folder objects](#the-folder-object) of the folders that were updated.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /folders`
|
||
|
||
```json
|
||
{
|
||
"keys": ["fac21847-d5ce-4e4b-a288-9abafbdfbc87", "a5bdb793-dd85-4ac9-882a-b42862092983"],
|
||
"data": {
|
||
"parent": "d97c2e0e-293d-4eb5-9e1c-27d3460ad29d"
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```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
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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',
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Delete a Folder
|
||
|
||
Delete an existing folder.
|
||
|
||
::: tip Files
|
||
|
||
Any files in this folder will be moved to the root folder.
|
||
|
||
:::
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /folders/:id`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
delete_folders_item(id: ID!): delete_one
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, deleteFolder } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(deleteFolder(folder_id));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
### Response
|
||
|
||
Empty body.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /folders/a5bdb793-dd85-4ac9-882a-b42862092983`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
delete_folders_item(id: "fac21847-d5ce-4e4b-a288-9abafbdfbc87") {
|
||
id
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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'));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Delete Multiple Folders
|
||
|
||
Delete multiple existing folders.
|
||
|
||
::: tip Files
|
||
|
||
Any files in these folders will be moved to the root folder.
|
||
|
||
:::
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /folders`
|
||
|
||
Provide an array of item IDs as your request body.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
delete_folders_items(ids: [ID!]!): delete_many
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, deleteFolders } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(deleteFolders(folder_id_array));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Request Body
|
||
|
||
An array of folder primary keys.
|
||
|
||
### Returns
|
||
|
||
Empty body.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /folders`
|
||
|
||
```json
|
||
["d97c2e0e-293d-4eb5-9e1c-27d3460ad29d", "fc02d733-95b8-4e27-bd4b-08a32cbe4e66"]
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
```graphql
|
||
mutation {
|
||
delete_folders_items(ids: ["fac21847-d5ce-4e4b-a288-9abafbdfbc87", "a5bdb793-dd85-4ac9-882a-b42862092983"]) {
|
||
ids
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
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'])
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|