Skip to main content

​
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('Created at:', material.createdAt);
console.log('Updated at:', material.updatedAt);

​
List All Materials

Get all materials in your organization, optionally filtered by folder. 
// Get all materials with pagination
const allMaterials = await client.v1.materials.list({
  limit: '50',
  page: '1'
});

// Get materials in a specific folder with pagination
const folderMaterials = await client.v1.materials.list({
  folderId: 'folder_123',
  limit: '20',
  page: '1'
});

console.log(`Found ${allMaterials.materials?.length || 0} materials`);
console.log(`Total materials: ${allMaterials.totalCount}`);
console.log(`Page ${allMaterials.page} of ${allMaterials.totalPages}`);

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

​
Update Material Reference

Update the reference information (title and URL) for an existing material. This is useful for adding or updating citation information. 
const updatedMaterial = await client.v1.materials.update('mat_123abc', {
  references: [
    {
      title: 'Introduction to Biology, 3rd Edition',
      url: 'https://example.com/biology-textbook'
    }
  ]
});

console.log('Material updated:', updatedMaterial._id);

​
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);
⌘I