GET /:project/files
# Files
Files can be saved in any given location. Directus has a powerful assets endpoint that can be used to generate thumbnails for images on the fly.
# The File Object
# Attributes
# id integer
Unique identifier for the file.
# storage string
Where the file is stored. Either local for the local filesystem or the name of the storage adapter (for example s3).
# filename_disk string
Name of the file on disk. By default, Directus uses a random hash for the filename.
# filename_download string
How you want to the file to be named when it's being downloaded.
# title string
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
# type string
MIME type of the file.
# uploaded_by user
Who uploaded the file.
# uploaded_on datetime
When the file was uploaded.
# charset string
Character set of the file.
# filesize integer
Size of the file in bytes.
# width integer
Width of the file in pixels. Only applies to images.
# height integer
Height of the file in pixels. Only applies to images.
# duration integer
Duration of the file in seconds. Only applies to audio and video.
# embed string
Where the file was embedded from.
# folder folder object
Virtual folder where this file resides in.
# description string
Description for the file.
# location string
Where the file was created. Is automatically populated based on EXIF data for images.
# tags csv, string
Tags for the file. Is automatically populated based on EXIF data for images.
# checksum string
Represents the sum of the correct digits of the file, can be used to detect errors in and duplicates of the file later.
# private_hash string
Random hash used to access the file privately. This can be rotated to prevent unauthorized access to the file.
# metadata key/value
User provided miscellaneous key value pairs that serve as additional metadata for the file.
# data.full_url string
Full URL to the original file.
# data.url string
Relative URL to the original file.
# data.thumbnails array
List of all available asset sizes with links.
# data.thumbnails.url string
Full URL to the thumbnail.
# data.thumbnails.relative_url string
Relative URL to the thumbnail.
# data.thumbnails.dimension string
Width x height of the thumbnail.
# data.thumbnails.width integer
Width of the thumbnail in pixels.
# data.thumbnails.height integer
Height of the thumbnail in pixels.
# List the Files
List the files.
# Parameters
# project required
The project you're targetting.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# limit optional
A limit on the number of objects that are returned. Default is 200. Learn more
# offset optional
How many items to skip when fetching data. Default is 0. Learn more
# sort optional
How to sort the returned items. Learn more
# single optional
Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more
# status optional
Filter items by the given status. Learn more
# filter optional
Select items in collection by given conditions. Learn more
# q optional
Filter by items that contain the given search query in one of their fields. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns an array of file objects.
{
"data": [
{
"id": 3,
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"uploaded_by": 1,
"uploaded_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"folder": null,
"description": "",
"location": "",
"tags": [],
"checksum": "d41d8cd98f00b204e9800998ecf8427e",
"private_hash": "pnw7s9lqy68048g0",
"metadata": null,
"data": {
"full_url": "https://demo.directus.io/uploads/thumper/originals/a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"url": "/uploads/thumper/originals/a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"thumbnails": [
{
"url": "https://demo.directus.io/thumper/assets/pnw7s9lqy68048g0?key=directus-small-crop",
"relative_url": "/thumper/assets/pnw7s9lqy68048g0?key=directus-small-crop",
"dimension": "64x64",
"width": 64,
"height": 64
},
{ ... },
{ ... }
],
"embed": null
}
},
{ ... },
{ ... }
]
}
# Retrieve a File
Retrieve a single file by unique identifier.
# Parameters
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the file object for the given unique identifier.
GET /:project/files/:id
{
"data": {
"id": 3,
"storage": "local",
"filename_disk": "a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"filename_download": "avatar.jpg",
"title": "User Avatar",
"type": "image/jpeg",
"uploaded_by": 1,
"uploaded_on": "2019-12-03T00:10:15+00:00",
"charset": "binary",
"filesize": 137862,
"width": 800,
"height": 838,
"duration": 0,
"embed": null,
"folder": null,
"description": "",
"location": "",
"tags": [],
"checksum": "d41d8cd98f00b204e9800998ecf8427e",
"private_hash": "pnw7s9lqy68048g0",
"metadata": null,
"data": {
"full_url": "https://demo.directus.io/uploads/thumper/originals/a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"url": "/uploads/thumper/originals/a88c3b72-ac58-5436-a4ec-b2858531333a.jpg",
"thumbnails": [
{
"url": "https://demo.directus.io/thumper/assets/pnw7s9lqy68048g0?key=directus-small-crop",
"relative_url": "/thumper/assets/pnw7s9lqy68048g0?key=directus-small-crop",
"dimension": "64x64",
"width": 64,
"height": 64
}
],
"embed": null
}
}
}
# Create a File
Create a new file.
TIP
It's recommend to use multipart/form-data as encoding type for this request.
# Parameters
# project required
The project you're targetting.
# Attributes
# data required
Raw file data (multipart/form-data), base64 string of file data, or URL you want to embed.
# filename_download optional
How you want to the file to be named when it's being downloaded.
# title optional
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
# folder optional object
Virtual folder where this file resides in.
# description optional
Description for the file.
# location optional
Where the file was created. Is automatically populated based on EXIF data for images.
# tags optional, string
Tags for the file. Is automatically populated based on EXIF data for images.
# metadata optional/value
User provided miscellaneous key value pairs that serve as additional metadata for the file.
# Query
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the file object for the file that was just uploaded.
POST /:project/files
{
"data": "https://images.unsplash.com/photo-1576854531280-9087cfd26e86"
}
{
"data": {
"id": 50,
"storage": "local",
"filename_disk": "904695e3-bd5b-4ba5-a569-6f481f08a285.jpeg",
"filename_download": "photo-1576854531280-9087cfd26e86.jpeg",
"title": "Photo 1576854531280 9087cfd26e86",
"type": "image/jpeg",
"uploaded_by": 1,
"uploaded_on": "2020-01-14T17:14:22+00:00",
"charset": "binary",
"filesize": 17585956,
"width": 6000,
"height": 4000,
"duration": 0,
"embed": null,
"folder": null,
"description": "",
"location": "",
"tags": [
"photo by dylan nolte"
],
"checksum": "9d58a1f44b9bcf9faca50ff240ff3a36",
"private_hash": "2aoxvcqi1jvooo8c",
"metadata": null,
"data": {
"full_url": "https://demo.directus.io/uploads/thumper/originals/904695e3-bd5b-4ba5-a569-6f481f08a285.jpeg",
"url": "/uploads/thumper/originals/904695e3-bd5b-4ba5-a569-6f481f08a285.jpeg",
"thumbnails": [
{
"url": "https://demo.directus.io/thumper/assets/2aoxvcqi1jvooo8c?key=directus-small-crop",
"relative_url": "/thumper/assets/2aoxvcqi1jvooo8c?key=directus-small-crop",
"dimension": "64x64",
"width": 64,
"height": 64
},
{ ... },
{ ... }
],
"embed": null
}
}
}
# Update a File
Update an existing file
# Parameters
# Attributes
# data required
Raw file data (multipart/form-data), base64 string of file data, or URL you want to embed.
# filename_disk optional
Name of the file on disk.
# filename_download optional
How you want to the file to be named when it's being downloaded.
# title optional
Title for the file. Is extracted from the filename on upload, but can be edited by the user.
# folder optional object
Virtual folder where this file resides in.
# description optional
Description for the file.
# location optional
Where the file was created. Is automatically populated based on EXIF data for images.
# tags optional, string
Tags for the file. Is automatically populated based on EXIF data for images.
# metadata optional/value
User provided miscellaneous key value pairs that serve as additional metadata for the file.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the file object for the file that was just updated.
PATCH /:project/files/:id
{
"title": "Dylan's Photo"
}
{
"data": [{
"id": 50,
"storage": "local",
"filename_disk": "904695e3-bd5b-4ba5-a569-6f481f08a285.jpeg",
"filename_download": "photo-1576854531280-9087cfd26e86.jpeg",
"title": "Dylan's Photo",
"type": "image/jpeg",
"uploaded_by": 1,
"uploaded_on": "2020-01-14T17:14:22+00:00",
"charset": "binary",
"filesize": 17585956,
"width": 6000,
"height": 4000,
"duration": 0,
"embed": null,
"folder": null,
"description": "",
"location": "",
"tags": [
"photo by dylan nolte"
],
"checksum": "9d58a1f44b9bcf9faca50ff240ff3a36",
"private_hash": "2aoxvcqi1jvooo8c",
"metadata": null,
"data": {
"full_url": "https://demo.directus.io/uploads/thumper/originals/904695e3-bd5b-4ba5-a569-6f481f08a285.jpeg",
"url": "/uploads/thumper/originals/904695e3-bd5b-4ba5-a569-6f481f08a285.jpeg",
"thumbnails": [
{
"url": "https://demo.directus.io/thumper/assets/2aoxvcqi1jvooo8c?key=directus-small-crop",
"relative_url": "/thumper/assets/2aoxvcqi1jvooo8c?key=directus-small-crop",
"dimension": "64x64",
"width": 64,
"height": 64
},
{ ... },
{ ... }
],
"embed": null
}
}]
}
# Delete a File
DELETE /:project/files/:id
# List File Revisions
List the revisions made to the given file.
# Parameters
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# limit optional
A limit on the number of objects that are returned. Default is 200. Learn more
# offset optional
How many items to skip when fetching data. Default is 0. Learn more
# page optional
Cursor for use in pagination. Often used in combination with limit. Learn more
# sort optional
How to sort the returned items. Learn more
# single optional
Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more
# filter optional
Select items in collection by given conditions. Learn more
# q optional
Filter by items that contain the given search query in one of their fields. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns an array of revision objects.
GET /:project/files/:id/revisions
{
"data": [
{
"id": 54,
"activity": 67,
"collection": "directus_files",
"item": "1",
"data": {
"id": "1",
"storage": "local",
"filename": "28596128-90a0-5872-ba5e-ecb063407146.jpg",
"title": "Green Fern Plants 1028223",
"type": "image/jpeg",
"uploaded_by": "1",
"uploaded_on": "2019-11-06 20:30:17",
"charset": "binary",
"filesize": "3017750",
"width": "5184",
"height": "3456",
"duration": "0",
"embed": null,
"folder": null,
"description": "",
"location": "",
"tags": [],
"checksum": "8d8bd7c4d1fae9e4d6e3b08c54f2a5df",
"metadata": null,
"data": {
"full_url": "http://localhost:8080/uploads/_/originals/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"url": "/uploads/_/originals/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"thumbnails": [
{
"url": "http://localhost:8080/thumbnail/_/200/200/crop/good/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"relative_url": "/thumbnail/_/200/200/crop/good/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"dimension": "200x200",
"width": 200,
"height": 200
}
],
"embed": null
}
},
"delta": {
"filename": "green-fern-plants-1028223.jpg",
"uploaded_by": 1,
"uploaded_on": "2019-11-06 15:30:17"
},
"parent_collection": null,
"parent_item": null,
"parent_changed": false
},
{ ... },
{ ... }
]
}
# Retrieve a File Revision
Retrieve a single revision of the file by offset.
# Parameters
# project required
The project you're targetting.
# collection required
Unique identifier of the collection the item resides in.
# offset required
How many revisions to go back in time.
# Query
# fields optional
Control what fields are being returned in the object. Learn more
# meta optional
What metadata to return in the response. Learn more
# Returns
Returns the revision object for the given unique identifier.
GET /:project/files/:id/revisions/:offset
{
"data": {
"id": 54,
"activity": 67,
"collection": "directus_files",
"item": "1",
"data": {
"id": "1",
"storage": "local",
"filename": "28596128-90a0-5872-ba5e-ecb063407146.jpg",
"title": "Green Fern Plants 1028223",
"type": "image\/jpeg",
"uploaded_by": "1",
"uploaded_on": "2019-11-06 20:30:17",
"charset": "binary",
"filesize": "3017750",
"width": "5184",
"height": "3456",
"duration": "0",
"embed": null,
"folder": null,
"description": "",
"location": "",
"tags": [],
"checksum": "8d8bd7c4d1fae9e4d6e3b08c54f2a5df",
"metadata": null,
"data": {
"full_url": "http:\/\/localhost:8080\/uploads\/_\/originals\/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"url": "\/uploads\/_\/originals\/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"thumbnails": [
{
"url": "http:\/\/localhost:8080\/thumbnail\/_\/200\/200\/crop\/good\/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"relative_url": "\/thumbnail\/_\/200\/200\/crop\/good\/28596128-90a0-5872-ba5e-ecb063407146.jpg",
"dimension": "200x200",
"width": 200,
"height": 200
}
],
"embed": null
}
},
"delta": {
"filename": "green-fern-plants-1028223.jpg",
"uploaded_by": 1,
"uploaded_on": "2019-11-06 15:30:17"
},
"parent_collection": null,
"parent_item": null,
"parent_changed": false
}
}