SDK Files Operations

Upload, manage, and retrieve files in Directus

Overview

The Directus SDK provides comprehensive file management capabilities, including uploading files, importing from URLs, retrieving file metadata, and managing file organization.

Read Operations

Read All Files

Retrieve a list of all files:

TypeScript

import { createDirectus, rest, readFiles } from '@directus/sdk';

const client = createDirectus<Schema>('https://your-directus-url.com')
  .with(rest());

const files = await client.request(
  readFiles()
);

files.forEach(file => {
  console.log(file.filename_download);
  console.log(file.type);
  console.log(file.filesize);
});

JavaScript

import { createDirectus, rest, readFiles } from '@directus/sdk';

const client = createDirectus('https://your-directus-url.com')
  .with(rest());

const files = await client.request(
  readFiles()
);

Read Files with Query

Filter, sort, and paginate files:

TypeScript

import { readFiles } from '@directus/sdk';

const images = await client.request(
  readFiles({
    filter: {
      type: { _starts_with: 'image/' },
    },
    sort: ['-uploaded_on'],
    limit: 20,
    fields: ['id', 'filename_download', 'type', 'filesize', 'width', 'height'],
  })
);

JavaScript

import { readFiles } from '@directus/sdk';

const images = await client.request(
  readFiles({
    filter: {
      type: { _starts_with: 'image/' },
    },
    sort: ['-uploaded_on'],
    limit: 20,
  })
);

Read Single File

Retrieve a specific file by ID:

TypeScript

import { readFile } from '@directus/sdk';

const file = await client.request(
  readFile('file-id-here')
);

console.log(file.filename_download);
console.log(file.title);
console.log(file.description);

JavaScript

import { readFile } from '@directus/sdk';

const file = await client.request(
  readFile('file-id-here')
);

Upload Operations

Upload Single File

Upload a file using FormData:

TypeScript

import { uploadFiles } from '@directus/sdk';

// Browser example
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('title', 'My Image');
formData.append('folder', 'folder-id');

const uploadedFile = await client.request(
  uploadFiles(formData)
);

console.log(uploadedFile.id);

JavaScript

import { uploadFiles } from '@directus/sdk';

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('title', 'My Image');

const uploadedFile = await client.request(
  uploadFiles(formData)
);

Upload with Metadata

Include additional metadata with your file upload:

TypeScript

import { uploadFiles } from '@directus/sdk';

const formData = new FormData();
formData.append('file', file);
formData.append('title', 'Product Image');
formData.append('description', 'Main product photo');
formData.append('folder', 'products-folder-id');
formData.append('tags', JSON.stringify(['product', 'featured']));

const uploadedFile = await client.request(
  uploadFiles(formData, {
    fields: ['*'],
  })
);

JavaScript

import { uploadFiles } from '@directus/sdk';

const formData = new FormData();
formData.append('file', file);
formData.append('title', 'Product Image');
formData.append('folder', 'products-folder-id');

const uploadedFile = await client.request(
  uploadFiles(formData)
);

Import File from URL

Import a file directly from a URL:

TypeScript

import { importFile } from '@directus/sdk';

const importedFile = await client.request(
  importFile(
    'https://example.com/image.jpg',
    {
      title: 'Imported Image',
      description: 'Image imported from URL',
      folder: 'folder-id',
    }
  )
);

console.log(importedFile.id);

JavaScript

import { importFile } from '@directus/sdk';

const importedFile = await client.request(
  importFile('https://example.com/image.jpg', {
    title: 'Imported Image',
  })
);

Update Operations

Update File Metadata

Update file metadata without re-uploading:

TypeScript

import { updateFile } from '@directus/sdk';

const updatedFile = await client.request(
  updateFile('file-id', {
    title: 'Updated Title',
    description: 'New description',
    tags: ['updated', 'featured'],
  })
);

JavaScript

import { updateFile } from '@directus/sdk';

const updatedFile = await client.request(
  updateFile('file-id', {
    title: 'Updated Title',
  })
);

Update Multiple Files

TypeScript

import { updateFiles } from '@directus/sdk';

const updatedFiles = await client.request(
  updateFiles(['file-id-1', 'file-id-2'], {
    folder: 'new-folder-id',
  })
);

JavaScript

import { updateFiles } from '@directus/sdk';

const updatedFiles = await client.request(
  updateFiles(['file-id-1', 'file-id-2'], {
    folder: 'new-folder-id',
  })
);

Delete Operations

Delete Single File

TypeScript

import { deleteFile } from '@directus/sdk';

await client.request(
  deleteFile('file-id')
);

JavaScript

import { deleteFile } from '@directus/sdk';

await client.request(deleteFile('file-id'));

Delete Multiple Files

TypeScript

import { deleteFiles } from '@directus/sdk';

await client.request(
  deleteFiles(['file-id-1', 'file-id-2', 'file-id-3'])
);

JavaScript

import { deleteFiles } from '@directus/sdk';

await client.request(
  deleteFiles(['file-id-1', 'file-id-2'])
);

File Properties

The DirectusFile object contains these key properties:

interface DirectusFile {
  id: string;
  storage: string;
  filename_disk: string;
  filename_download: string;
  title: string | null;
  type: string;
  folder: string | null;
  uploaded_by: string | null;
  uploaded_on: string;
  modified_by: string | null;
  modified_on: string;
  charset: string | null;
  filesize: number;
  width: number | null;
  height: number | null;
  duration: number | null;
  embed: string | null;
  description: string | null;
  location: string | null;
  tags: string[] | null;
  metadata: Record<string, any> | null;
}

Accessing File URLs

To access the actual file, construct the URL:

TypeScript

const file = await client.request(
  readFile('file-id')
);

const fileUrl = `${client.url}/assets/${file.id}`;

// With transformations for images
const thumbnailUrl = `${client.url}/assets/${file.id}?width=200&height=200&fit=cover`;

JavaScript

const file = await client.request(
  readFile('file-id')
);

const fileUrl = `${client.url}/assets/${file.id}`;

Working with Folders

Read Folders

TypeScript

import { readFolders } from '@directus/sdk';

const folders = await client.request(
  readFolders()
);

folders.forEach(folder => {
  console.log(folder.name);
  console.log(folder.parent); // Parent folder ID
});

JavaScript

import { readFolders } from '@directus/sdk';

const folders = await client.request(
  readFolders()
);

Create Folder

TypeScript

import { createFolder } from '@directus/sdk';

const newFolder = await client.request(
  createFolder({
    name: 'Products',
    parent: null, // Root level
  })
);

console.log(newFolder.id);

JavaScript

import { createFolder } from '@directus/sdk';

const newFolder = await client.request(
  createFolder({
    name: 'Products',
  })
);

Node.js File Upload Example

Upload files in a Node.js environment:

import { createDirectus, rest, staticToken, uploadFiles } from '@directus/sdk';
import { readFile } from 'fs/promises';
import FormData from 'form-data';

const client = createDirectus('https://your-directus-url.com')
  .with(rest())
  .with(staticToken('your-token'));

const fileBuffer = await readFile('./path/to/image.jpg');
const formData = new FormData();
formData.append('file', fileBuffer, 'image.jpg');
formData.append('title', 'Uploaded from Node.js');

const uploadedFile = await client.request(
  uploadFiles(formData as any)
);

console.log(`Uploaded file ID: ${uploadedFile.id}`);

Type Signatures

// Read operations
function readFiles<Schema, TQuery>(
  query?: TQuery
): RestCommand<DirectusFile<Schema>[], Schema>;

function readFile<Schema, TQuery>(
  key: string,
  query?: TQuery
): RestCommand<DirectusFile<Schema>, Schema>;

// Upload operations
function uploadFiles<Schema, TQuery>(
  data: FormData,
  query?: TQuery
): RestCommand<DirectusFile<Schema>, Schema>;

function importFile<Schema, TQuery>(
  url: string,
  data?: Partial<DirectusFile<Schema>>,
  query?: TQuery
): RestCommand<DirectusFile<Schema>, Schema>;

// Update operations
function updateFile<Schema, TQuery>(
  key: string,
  data: Partial<DirectusFile<Schema>>,
  query?: TQuery
): RestCommand<DirectusFile<Schema>, Schema>;

// Delete operations
function deleteFile<Schema>(
  key: string
): RestCommand<void, Schema>;

Next Steps

Items Operations

Link files to collection items

Users

Manage user avatars and files

Assets API

Transform and optimize images

Storage

Configure file storage adapters