mirror of https://github.com/directus/directus.git synced 2026-01-23 03:08:08 -05:00

Files

Rijk van Zanten df22a58c6a Update in-app docs (#3989 )

* Fix root redirect

* Fix html in headings

* Add graphql syntax mode

* Install markdown-it + plugins

* Fix file copying on mac

* Replace md rendering engine

* Fix wrong links in guides

* Scroll to top on every route change

* Update in-app links

* Fix home redirect

* Fix deep-linking paths

* Add to reference

* Fix nested group scoping

* Fix open path reference

2021-02-09 18:31:25 -05:00

15 KiB

Raw Blame History

pageClass

pageClass
page-reference

Files

Files are the objects that contain information about the file managed through Directus. If you're looking for the actual file data, including thumbnails, see the /assets endpoint. Learn more about Files.

toc

The File Object

id uuid
Primary key of the file

storage string
Storage adapter used for the file.

filename_disk string
Name of the file as saved on the storage adapter.

filename_download string
Preferred filename when file is downloaded.

title string
Title for the file.

type string
Mimetype of the file.

folder many-to-one
What (virtual) folder the file is in. Many-to-one to folders.

uploaded_by many-to-one
Who uploaded the file. Many-to-one to users.

uploaded_on datetime
When the file was uploaded.

modified_by many-to-one
Who updated the file last. Many-to-one to users.

filesize number
Size of the file in bytes.

width number
If the file is a(n) image/video, it's the width in px.

height number
If the file is a(n) image/video, it's the height in px.

duration number
If the file contains audio/video, it's the duration in milliseconds.

description string
Description of the file.

location string
Location of the file.

tags csv
Tags for the file.

metadata object
Any additional metadata Directus was able to scrape from the file. For images, this includes EXIF, IPTC, and ICC information.

{
	"id": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb",
	"storage": "local",
	"filename_disk": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb.jpeg",
	"filename_download": "paulo-silva-vSRgXtQuns8-unsplash.jpg",
	"title": "Paulo Silva (via Unsplash)",
	"type": "image/jpeg",
	"folder": null,
	"uploaded_by": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
	"uploaded_on": "2021-02-04T11:37:41-05:00",
	"modified_by": null,
	"modified_on": "2021-02-04T11:37:42-05:00",
	"filesize": 3442252,
	"width": 3456,
	"height": 5184,
	"duration": null,
	"description": null,
	"location": null,
	"tags": null,
	"metadata": {
		"icc": {
			"version": "2.1",
			"intent": "Perceptual",
			"cmm": "lcms",
			"deviceClass": "Monitor",
			"colorSpace": "RGB",
			"connectionSpace": "XYZ",
			"platform": "Apple",
			"creator": "lcms",
			"description": "c2",
			"copyright": ""
		}
	}
}

List Files

List all files that exist in Directus.

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit file objects. If no items are available, data will be an empty array.

GET /files

{
	"data": [
		{
			"id": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb",
			"storage": "local",
			"filename_disk": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb.jpeg",
			"filename_download": "paulo-silva-vSRgXtQuns8-unsplash.jpg",
			"title": "Paulo Silva (via Unsplash)",
			"type": "image/jpeg",
			"folder": null,
			"uploaded_by": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
			"uploaded_on": "2021-02-04T11:37:41-05:00",
			"modified_by": null,
			"modified_on": "2021-02-04T11:37:42-05:00",
			"charset": null,
			"filesize": 3442252,
			"width": 3456,
			"height": 5184,
			"duration": null,
			"embed": null,
			"description": null,
			"location": null,
			"tags": null,
			"metadata": {
				"icc": {
					"version": "2.1",
					"intent": "Perceptual",
					"cmm": "lcms",
					"deviceClass": "Monitor",
					"colorSpace": "RGB",
					"connectionSpace": "XYZ",
					"platform": "Apple",
					"creator": "lcms",
					"description": "c2",
					"copyright": ""
				}
			}
		},
		{...},
		{...}
	]
}

Retrieve a File

Retrieve a single file by primary key.

Query Parameters

Supports all global query parameters.

Returns

Returns a file object if a valid primary key was provided.

GET /files/:id

{
	"data": {
		"id": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb",
		"storage": "local",
		"filename_disk": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb.jpeg",
		"filename_download": "paulo-silva-vSRgXtQuns8-unsplash.jpg",
		"title": "Paulo Silva (via Unsplash)",
		"type": "image/jpeg",
		"folder": null,
		"uploaded_by": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
		"uploaded_on": "2021-02-04T11:37:41-05:00",
		"modified_by": null,
		"modified_on": "2021-02-04T11:37:42-05:00",
		"charset": null,
		"filesize": 3442252,
		"width": 3456,
		"height": 5184,
		"duration": null,
		"embed": null,
		"description": null,
		"location": null,
		"tags": null,
		"metadata": {
			"icc": {
				"version": "2.1",
				"intent": "Perceptual",
				"cmm": "lcms",
				"deviceClass": "Monitor",
				"colorSpace": "RGB",
				"connectionSpace": "XYZ",
				"platform": "Apple",
				"creator": "lcms",
				"description": "c2",
				"copyright": ""
			}
		}
	}
}

Upload a File

Upload/create a new file.

To upload a file, use multipart/form-data as the encoding type, instead of JSON.

The file contents has to to be provided in a part called file. All other properties of the file object can be provided as parts as well.

::: tip Order Matters

Make sure to define the non-file properties first. This ensures that the file metadata is associated with the correct file.

:::

You can upload multiple files at a time by repeating the payload with different contents, for example:

--__X_BOUNDARY__
Content-Disposition: form-data; name="title"

Example
--__X_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="paulo-silva-vSRgXtQuns8-unsplash.jpg"
Content-Type: image/jpeg

// binary data

--__X_BOUNDARY__
Content-Disposition: form-data; name="title"

Another Title
--__X_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="mae-mu-GFhqNX1gE9E-unsplash.jpg"
Content-Type: image/jpeg

// binary data

In JavaScript, this can be achieved using the native FormData class:

import axios from 'axios';

const fileInput = document.querySelector('input[type="file"]');
const formData = new FormData();

formData.append('title', 'My First File');
formData.append('file', fileInput.files[0]);

await axios.post('/files', formData);

Query Parameters

Supports all global query parameters.

Returns

Returns the file object for the uploaded file, or an array of file objects if multiple files were uploaded at once.

POST /files

// Request

Content-Type: multipart/form-data; charset=utf-8; boundary=__X_BOUNDARY__
Content-Length: 3442422

--__X_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="paulo-silva-vSRgXtQuns8-unsplash.jpg"
Content-Type: image/jpeg

ÿØÿàJFIFHHÿâICC_PROFILElcmsmntrRGB XYZ Ü)9acspAPPLöÖÓ-lcms
descü^cprt\wtpthbkpt|rXYZgXYZ¤bXYZ¸rTRCÌ@gTRCÌ@bTRCÌ@descc2textIXXYZ öÖÓ-XYZ 3¤XYZ o¢8õXYZ b·ÚXYZ $ ¶ÏcurvËÉckö?Q4!ñ)2;FQw]íkpz±|¬i¿}ÓÃé0ÿÿÿÛ

// Response

{
	"data": {
		"id": "cbda3d4f-5f84-4357-97ba-0851aba68dee",
		"storage": "local",
		"filename_disk": "cbda3d4f-5f84-4357-97ba-0851aba68dee.jpeg",
		"filename_download": "paulo-silva-vSRgXtQuns8-unsplash.jpg",
		"title": "Paulo Silva (via Unsplash)",
		"type": "image/jpeg",
		"folder": null,
		"uploaded_by": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
		"uploaded_on": "2021-02-04T12:07:50-05:00",
		"modified_by": null,
		"modified_on": "2021-02-04T12:07:50-05:00",
		"charset": null,
		"filesize": 3442252,
		"width": 3456,
		"height": 5184,
		"duration": null,
		"embed": null,
		"description": null,
		"location": null,
		"tags": null,
		"metadata": {
			"icc": {
				"version": "2.1",
				"intent": "Perceptual",
				"cmm": "lcms",
				"deviceClass": "Monitor",
				"colorSpace": "RGB",
				"connectionSpace": "XYZ",
				"platform": "Apple",
				"creator": "lcms",
				"description": "c2",
				"copyright": ""
			}
		}
	}
}

Import a File

Import a file from the web

Query Parameters

Supports all global query parameters.

Request Body

url Required
The URL to download the file from.

data
Any of the file object's properties.

Returns

Returns the file object for the imported file.

POST /files/import

// Request

{
	"url": "https://source.unsplash.com/random",
	"data": {
		"title": "Example"
	}
}

// Response

{
	"data": {
		"id": "d17c10aa-0bad-4864-9296-84f522c753e5",
		"storage": "local",
		"filename_disk": "d17c10aa-0bad-4864-9296-84f522c753e5.jpeg",
		"filename_download": "photo-1610484637796-22140be4b7ef",
		"title": "Example",
		"type": "image/jpeg",
		"folder": null,
		"uploaded_by": null,
		"uploaded_on": "2021-02-04T12:31:59-05:00",
		"modified_by": null,
		"modified_on": "2021-02-04T12:31:59-05:00",
		"charset": null,
		"filesize": 167141,
		"width": 1080,
		"height": 1350,
		"duration": null,
		"embed": null,
		"description": null,
		"location": null,
		"tags": null,
		"metadata": {
			"icc": {
				"version": "2.1",
				"intent": "Perceptual",
				"cmm": "lcms",
				"deviceClass": "Monitor",
				"colorSpace": "RGB",
				"connectionSpace": "XYZ",
				"platform": "Apple",
				"creator": "lcms",
				"description": "c2",
				"copyright": ""
			}
		}
	}
}

Update a File

Update an existing file, and/or replace it's file contents.

Query Parameters

Supports all global query parameters.

Request Body

You can either submit a JSON object consisting of a partial file object to update the file meta, or send a multipart/form-data request to replace the file contents on disk. See Upload a File for more information on the structure of this multipart/form-data request.

Returns

Returns the file object for the updated file.

PATCH /files/:id

// Request

{
	"title": "Example"
}

// Response

{
	"data": {
		"id": "d17c10aa-0bad-4864-9296-84f522c753e5",
		"storage": "local",
		"filename_disk": "d17c10aa-0bad-4864-9296-84f522c753e5.jpeg",
		"filename_download": "photo-1610484637796-22140be4b7ef",
		"title": "Example",
		"type": "image/jpeg",
		"folder": null,
		"uploaded_by": null,
		"uploaded_on": "2021-02-04T12:31:59-05:00",
		"modified_by": null,
		"modified_on": "2021-02-04T12:31:59-05:00",
		"charset": null,
		"filesize": 167141,
		"width": 1080,
		"height": 1350,
		"duration": null,
		"embed": null,
		"description": null,
		"location": null,
		"tags": null,
		"metadata": {
			"icc": {
				"version": "2.1",
				"intent": "Perceptual",
				"cmm": "lcms",
				"deviceClass": "Monitor",
				"colorSpace": "RGB",
				"connectionSpace": "XYZ",
				"platform": "Apple",
				"creator": "lcms",
				"description": "c2",
				"copyright": ""
			}
		}
	}
}

Update Multiple Files

Update multiple files at the same time.

Query Parameters

Supports all global query parameters.

Request Body

There's two ways to update files: Update multiple files to different values, or to update multiple files to the same values.

Different Values

Post an array of (partial) file objects. Make sure to include id for every object in the array in order for Directus to be able to know what the file is you're updating.

Same Value

Alternatively, you can send the following:

keys Required
Array of primary keys of the files you'd like to update.

data Required
Any of the file object's properties.

Returns

Returns the file objects for the updated files.

PATCH /files

// Request

// Multiple files, different values
[
	{
		"id": "d17c10aa-0bad-4864-9296-84f522c753e5",
		"title": "New York City"
	},
	{
		"id": "b6123925-2fc0-4a30-9d86-863eafc0a6e7",
		"title": "Amsterdam"
	}
]

// Multiple files, same value
{
	"keys": ["b6123925-2fc0-4a30-9d86-863eafc0a6e7", "d17c10aa-0bad-4864-9296-84f522c753e5"],
	"data": {
		"tags": "cities"
	}
}

// Response

{
	"data": [
		{
			"id": "d17c10aa-0bad-4864-9296-84f522c753e5",
			"storage": "local",
			"filename_disk": "d17c10aa-0bad-4864-9296-84f522c753e5.jpeg",
			"filename_download": "photo-1610484637796-22140be4b7ef",
			"title": "Example",
			"type": "image/jpeg",
			"folder": null,
			"uploaded_by": null,
			"uploaded_on": "2021-02-04T12:31:59-05:00",
			"modified_by": null,
			"modified_on": "2021-02-04T12:31:59-05:00",
			"charset": null,
			"filesize": 167141,
			"width": 1080,
			"height": 1350,
			"duration": null,
			"embed": null,
			"description": null,
			"location": null,
			"tags": null,
			"metadata": {
				"icc": {
					"version": "2.1",
					"intent": "Perceptual",
					"cmm": "lcms",
					"deviceClass": "Monitor",
					"colorSpace": "RGB",
					"connectionSpace": "XYZ",
					"platform": "Apple",
					"creator": "lcms",
					"description": "c2",
					"copyright": ""
				}
			}
		},
		{...}
	]
}

Delete a File

Delete an existing file.

::: danger Destructive

This will also delete the file from disk.

:::

Query Parameters

Supports all global query parameters.

Returns

Empty response.

DELETE /files/:id

// Empty Response

Delete Multiple Files

Delete multiple files at once.

::: danger Destructive

This will also delete the files from disk.

:::

Request Body

Array of file primary keys

Returns

Empty response.

DELETE /files

// Request
["d17c10aa-0bad-4864-9296-84f522c753e5", "b6123925-2fc0-4a30-9d86-863eafc0a6e7"]

// Empty Response

15 KiB Raw Blame History Unescape Escape

Files

The File Object

List Files

Query Parameters

Returns

Retrieve a File

Query Parameters

Returns

Upload a File

Query Parameters

Returns

Import a File

Query Parameters

Request Body

Returns

Update a File

Query Parameters

Request Body

Returns

Update Multiple Files

Query Parameters

Request Body

Different Values

Same Value

Returns

Delete a File

Query Parameters

Returns

Delete Multiple Files

Request Body

Returns

15 KiB

Raw Blame History