Files
List Files
List all files that exist in Directus.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
How many items to skip when fetching data.
How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
What metadata to return in the response.
Responses
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
IPTC, Exif, and ICC metadata extracted from file
When the file was last uploaded/replaced.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
GET /files
import { createDirectus, rest, readFiles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readFile(file_id, query_object));
POST /graphql/system
type Query {
files_by_id(id: ID!): directus_files
}
{
"data": [
{
"id": "8cbb43fe-4cdf-4991-8352-c461779cec02",
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"folder": null,
"uploaded_by": "63716273-0f29-4648-8a2a-2af2948f6f78",
"created_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"tags": [],
"metadata": {},
"uploaded_on": "2019-12-03T00:10:15+00:00"
}
],
"meta": {}
}
Upload a File
Upload a new file.
Request Body
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
When the file was last uploaded/replaced.
Responses
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
When the file was last uploaded/replaced.
POST /files
import { createDirectus, rest, uploadFiles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const formData = new FormData();
formData.append('file_1_property', 'Value');
formData.append('file', raw_file);
formData.append('file_2_property', 'Value');
formData.append('file', raw_file_2);
const result = await client.request(uploadFiles(formData));
//Not currently supported by GraphQL.
{
"data": {
"id": "8cbb43fe-4cdf-4991-8352-c461779cec02",
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"folder": null,
"uploaded_by": "63716273-0f29-4648-8a2a-2af2948f6f78",
"created_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"tags": [],
"metadata": {},
"uploaded_on": "2019-12-03T00:10:15+00:00"
}
}
Delete Multiple Files
Delete multiple existing files at once. This will also delete the files from disk.
Responses
DELETE /files
import { createDirectus, rest, deleteFiles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteFiles(file_id_array));
//or
const result = await client.request(deleteFiles(query_object));
POST /graphql/system
type Mutation {
delete_files_items(ids: [ID!]!): delete_many
}
Update Multiple Files
Update multiple files at the same time.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
What metadata to return in the response.
How many items to skip when fetching data.
How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Request Body
Responses
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
IPTC, Exif, and ICC metadata extracted from file
When the file was last uploaded/replaced.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
PATCH /files
import { createDirectus, rest, updateFiles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateFiles(file_id_array, partial_file_object));
POST /graphql/system
type Mutation {
update_files_items(ids: [ID!]!, data: update_directus_files!): [directus_files]
}
{
"data": [
{
"id": "8cbb43fe-4cdf-4991-8352-c461779cec02",
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"folder": null,
"uploaded_by": "63716273-0f29-4648-8a2a-2af2948f6f78",
"created_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"tags": [],
"metadata": {},
"uploaded_on": "2019-12-03T00:10:15+00:00"
}
],
"meta": {}
}
Import a File
Import a file from the web
Request Body
The URL to download the file from.
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
When the file was last uploaded/replaced.
Responses
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
When the file was last uploaded/replaced.
POST /files/import
import { createDirectus, rest, importFile } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(importFile(file_url, file_object));
const result = await client.request(uploadFiles(formData));
POST /graphql/system
type Mutation {
import_file(url: String!, data: create_directus_files_input!): directus_files
}
{
"data": {
"id": "8cbb43fe-4cdf-4991-8352-c461779cec02",
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"folder": null,
"uploaded_by": "63716273-0f29-4648-8a2a-2af2948f6f78",
"created_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"tags": [],
"metadata": {},
"uploaded_on": "2019-12-03T00:10:15+00:00"
}
}
Retrieve a File
Retrieve a single file by primary key.
Query Parameters
Unique identifier for the object.
Control what fields are being returned in the object.
What metadata to return in the response.
Responses
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
When the file was last uploaded/replaced.
GET /files/{id}
import { createDirectus, rest, readFiles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readFile(file_id, query_object));
type Query {
files_by_id(id: ID!): directus_files
}
{
"data": {
"id": "8cbb43fe-4cdf-4991-8352-c461779cec02",
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"folder": null,
"uploaded_by": "63716273-0f29-4648-8a2a-2af2948f6f78",
"created_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"tags": [],
"metadata": {},
"uploaded_on": "2019-12-03T00:10:15+00:00"
}
}
Delete a File
Delete an existing file. This will also delete the file from disk.
Query Parameters
Unique identifier for the object.
Responses
DELETE /files/{id}
import { createDirectus, rest, deleteFile } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteFile(file_id));
POST /graphql/system
type Mutation {
delete_files_item(id: ID!): delete_one
}
Update a File
Update an existing file, and/or replace it's file contents.
Query Parameters
Unique identifier for the object.
Control what fields are being returned in the object.
What metadata to return in the response.
Request Body
Responses
Unique identifier for the file.
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
Name of the file on disk. By default, Directus uses a random hash for the filename.
How you want to the file to be named when it's being downloaded.
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
MIME type of the file.
Virtual folder where this file resides in.
Who uploaded the file.
When the file was created.
Character set of the file.
Size of the file in bytes.
Width of the file in pixels. Only applies to images.
Height of the file in pixels. Only applies to images.
Duration of the file in seconds. Only applies to audio and video.
Where the file was embedded from.
Description for the file.
Where the file was created. Is automatically populated based on Exif data for images.
Tags for the file. Is automatically populated based on Exif data for images.
When the file was last uploaded/replaced.
PATCH /files/{id}
import { createDirectus, rest, updateFile } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateFile(file_id, partial_file_object));
POST /graphql/system
type Mutation {
update_files_item(id: ID!, data: update_directus_files_input!): directus_files
}
{
"data": {
"id": "8cbb43fe-4cdf-4991-8352-c461779cec02",
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"folder": null,
"uploaded_by": "63716273-0f29-4648-8a2a-2af2948f6f78",
"created_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"tags": [],
"metadata": {},
"uploaded_on": "2019-12-03T00:10:15+00:00"
}
}