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.

Endpoints
   GET /:project/files
   GET /:project/files/:id
  POST /:project/files
 PATCH /:project/files/:id
DELETE /:project/files/:id
   GET /:project/files/:id/revisions
   GET /:project/files/:id/revisions/:offset

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.

File Object
{
  "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
  }
}

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.

Endpoint
   GET /:project/files
Response
{
  "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

project required

The project you're targetting.

id required

Unique identifier of the item.

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.

Endpoint
   GET /:project/files/:id
Response
{
  "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.

Endpoint
  POST /:project/files
Request
{
  "data": "https://images.unsplash.com/photo-1576854531280-9087cfd26e86"
}
Response
{
  "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

project required

The project you're targetting.

id required

Unique identifier of the item.

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.

Endpoint
 PATCH /:project/files/:id
Request
{
  "title": "Dylan's Photo"
}
Response
{
  "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 an existing file

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/files/:id

List File Revisions

List the revisions made to the given file.

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

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.

Endpoint
   GET /:project/files/:id/revisions
Response
{
  "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.

Endpoint
   GET /:project/files/:id/revisions/:offset
Response
{
  "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
  }
}