​
Overview

Once materials are uploaded, you can manage them by:
  • Moving materials between folders
  • Renaming materials
  • Deleting materials
  • Bulk operations
  • Retrieving material details
  • Downloading materials

​
Get Material Details

Retrieve details about a specific material including its content, metadata, and processing status. 
const material = await client.v1.materials.retrieve('mat_123abc');

console.log('Material:', material.name);
console.log('Status:', material.status);
console.log('Content type:', material.contentType);
console.log('Word count:', material.metadata.wordCount);
console.log('Images:', material.metadata.images.length);

​
List All Materials

Get all materials in your organization, optionally filtered by folder. 
// Get all materials
const allMaterials = await client.v1.materials.list();

// Get materials in a specific folder
const folderMaterials = await client.v1.materials.list({
  folderId: 'folder_123'
});

console.log(`Found ${allMaterials.length} materials`);

​
Move Material to Folder

Move a material to a different folder or to the root level. 
// Move to a folder
const movedMaterial = await client.v1.materials.move('mat_123abc', {
  folderId: 'folder_456def'
});

// Move to root (no folder)
const rootMaterial = await client.v1.materials.move('mat_123abc', {
  folderId: null
});

console.log('Material moved to:', movedMaterial.folderId || 'root');

​
Rename Material

Change the name of an existing material. 
const renamedMaterial = await client.v1.materials.rename('mat_123abc', {
  name: 'Biology Chapter 2 - Updated'
});

console.log('Material renamed to:', renamedMaterial.name);

​
Delete Material

Permanently delete a material. This is a soft delete - the material is marked as deleted but retained for audit purposes. 
await client.v1.materials.delete('mat_123abc');

console.log('Material deleted successfully');

​
Bulk Move Materials

Move multiple materials to a folder in a single operation. 
const materialIds = ['mat_123abc', 'mat_456def', 'mat_789ghi'];

const result = await client.v1.materials.bulk.move({
  materialIds,
  folderId: 'folder_999xyz'
});

console.log(`Moved ${result.movedCount} materials`);

​
Download Material

Get a temporary download URL for a material stored in S3. 
// Get download URL (expires in 1 hour by default)
const { downloadUrl } = await client.v1.materials.getDownloadURL('mat_123abc', {
  expiresIn: '3600'
});

// Get download URL with custom expiry (in seconds)
const { downloadUrl: customUrl } = await client.v1.materials.getDownloadURL('mat_123abc', {
  expiresIn: '7200' // 2 hours
});

console.log('Download URL:', downloadUrl);

​
Example: Complete Material Management Flow

Here’s a complete example showing the typical lifecycle of material management: 
// 1. Upload a material
const fileBuffer = await fs.promises.readFile(
  path.join(process.cwd(), 'biology-notes.pdf'),
);
const file = new File([fileBuffer], 'biology-notes.pdf', {
  type: 'application/pdf',
});

const material = await client.v1.materials.upload.uploadFile({
  file,
  name: 'Biology Notes v1'
});
console.log('Uploaded:', material._id);

// 2. Wait for processing
let status = 'processing';
while (status === 'processing') {
  await new Promise(resolve => setTimeout(resolve, 2000));
  const updated = await client.v1.materials.retrieve(material._id);
  status = updated.status;
}

// 3. Rename the material
const renamed = await client.v1.materials.rename(material._id, {
  name: 'Biology Notes - Final Version'
});

// 4. Move to a folder
const moved = await client.v1.materials.move(material._id, {
  folderId: 'folder_biology'
});

// 5. Get download URL
const { downloadUrl } = await client.v1.materials.getDownloadURL(material._id, {
  expiresIn: '3600'
});
console.log('Download from:', downloadUrl);

// 6. Eventually delete
// await client.v1.materials.delete(material._id);