SDK Files Operations

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
JavaScript

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);
});

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
JavaScript

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'],
  })
);

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
JavaScript

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);

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
JavaScript

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);

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
JavaScript

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: ['*'],
  })
);

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
JavaScript

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);

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
JavaScript

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

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

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

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

Update Multiple Files

TypeScript
JavaScript

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

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

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
JavaScript

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

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

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

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

Delete Multiple Files

TypeScript
JavaScript

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

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

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
JavaScript

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`;

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

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

Working with Folders

Read Folders

TypeScript
JavaScript

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
});

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

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

Create Folder

TypeScript
JavaScript

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

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

console.log(newFolder.id);

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

REST API

GraphQL

SDK

WebSocket

SDK Files Operations

Overview

Read Operations

Read All Files

Read Files with Query

Read Single File

Upload Operations

Upload Single File

Upload with Metadata

Import File from URL

Update Operations

Update File Metadata

Update Multiple Files

Delete Operations

Delete Single File

Delete Multiple Files

File Properties

Accessing File URLs

Working with Folders

Read Folders

Create Folder

Node.js File Upload Example

Type Signatures

Next Steps

Items Operations

Users

Assets API

Storage

​Overview

​Read Operations

​Read All Files

​Read Files with Query

​Read Single File

​Upload Operations

​Upload Single File

​Upload with Metadata

​Import File from URL

​Update Operations

​Update File Metadata

​Update Multiple Files

​Delete Operations

​Delete Single File

​Delete Multiple Files

​File Properties

​Accessing File URLs

​Working with Folders

​Read Folders

​Create Folder

​Node.js File Upload Example

​Type Signatures

​Next Steps

Items Operations

Users

Assets API

Storage

Overview

Read Operations

Read All Files

Read Files with Query

Read Single File

Upload Operations

Upload Single File

Upload with Metadata

Import File from URL

Update Operations

Update File Metadata

Update Multiple Files

Delete Operations

Delete Single File

Delete Multiple Files

File Properties

Accessing File URLs

Working with Folders

Read Folders

Create Folder

Node.js File Upload Example

Type Signatures

Next Steps