Skip to content
StudyFetch API

API Documentation

Managing Materials

9 min read

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.

JavaScript

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

Python

material = client.v1.materials.retrieve("mat_123abc")

print(f"Material: {material.name}")
print(f"Status: {material.status}")
print(f"Content type: {material.content_type}")
print(f"Word count: {material.metadata.word_count}")
print(f"Images: {len(material.metadata.images)}")

Java

import com.studyfetch.javasdk.models.v1.materials.MaterialResponse;

import com.studyfetch.javasdk.models.v1.materials.MaterialRetrieveParams;

MaterialResponse material = client.v1().materials().retrieve(
    MaterialRetrieveParams.builder()
        .id("mat_123abc")
        .build()
);

System.out.println("Material: " + material.name());
System.out.println("Status: " + material.status());
System.out.println("Content type: " + material.contentType());

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.Threading.Tasks;

public class GetMaterialDetails
{
    public static async Task GetDetails()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var material = await client.V1.Materials.Retrieve(new()
        {
            ID = "mat_123abc"
        });

        Console.WriteLine($"Material: {material.Name}");
        Console.WriteLine($"Status: {material.Status}");
        Console.WriteLine($"Content type: {material.ContentType}");
        Console.WriteLine($"Created at: {material.CreatedAt}");
        Console.WriteLine($"Updated at: {material.UpdatedAt}");
    }
}

List All Materials

Get all materials in your organization, optionally filtered by folder.

JavaScript

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

Python

# Get all materials with pagination
all_materials = client.v1.materials.list(
    limit="50",
    page="1"
)

# Get materials in a specific folder with pagination
folder_materials = client.v1.materials.list(
    folder_id="folder_123",
    limit="20",
    page="1"
)

print(f"Found {len(all_materials.data)} materials")
print(f"Total materials: {all_materials.total}")
print(f"Page {all_materials.page} of {all_materials.total_pages}")

Java

import com.studyfetch.javasdk.models.v1.materials.MaterialListParams;
import java.util.List;

// Get all materials with pagination
MaterialListParams allParams = MaterialListParams.builder()
    .limit("50")
    .page("1")
    .build();
MaterialListResponse allMaterials = client.v1().materials().list(allParams);

// Get materials in a specific folder with pagination
MaterialListParams folderParams = MaterialListParams.builder()
    .folderId("folder_123")
    .limit("20")
    .page("1")
    .build();
MaterialListResponse folderMaterials = client.v1().materials().list(folderParams);

System.out.println("Page " + allMaterials.page() + " of " + allMaterials.totalPages());

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.Threading.Tasks;

public class ListAllMaterials
{
    public static async Task ListMaterials()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Get all materials with pagination
        var allMaterials = await client.V1.Materials.List(new()
        {
            Limit = "50",
            Page = "1"
        });

        // Get materials in a specific folder with pagination
        var folderMaterials = await client.V1.Materials.List(new()
        {
            FolderID = "folder_123",
            Limit = "20",
            Page = "1"
        });

        Console.WriteLine($"Found {allMaterials.Materials?.Count ?? 0} materials");
        Console.WriteLine($"Total materials: {allMaterials.TotalCount}");
        Console.WriteLine($"Page {allMaterials.Page} of {allMaterials.TotalPages}");
    }
}

Move Material to Folder

Move a material to a different folder or to the root level.

JavaScript

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

Python

# Move to a folder
moved_material = client.v1.materials.move(
    material_id="mat_123abc",
    folder_id="folder_456def"
)

# Move to root (no folder)
root_material = client.v1.materials.move(
    material_id="mat_123abc",
    folder_id=None
)

print(f"Material moved to: {moved_material.folder_id or 'root'}")

Java

// The move method signature from the API docs shows it takes just an ID
// To move a material, you would typically:
// 1. Call move endpoint with material ID
// 2. Specify folder ID in request body

client.v1().materials().move(MaterialMoveParams.builder().id("mat_123abc").build());

System.out.println("Material moved successfully");

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.Threading.Tasks;

public class MoveMaterial
{
    public static async Task Move()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Move to a folder
        var movedMaterial = await client.V1.Materials.Move(new()
        {
            ID = "mat_123abc",
            FolderID = "folder_456def"
        });

        // Move to root (no folder)
        var rootMaterial = await client.V1.Materials.Move(new()
        {
            ID = "mat_123abc",
            FolderID = null
        });

        Console.WriteLine($"Material moved to: {movedMaterial.FolderID ?? "root"}");
    }
}

Rename Material

Change the name of an existing material.

JavaScript

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

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

Python

renamed_material = client.v1.materials.rename(
    material_id="mat_123abc",
    name="Biology Chapter 2 - Updated"
)

print(f"Material renamed to: {renamed_material.name}")

Java

import com.studyfetch.javasdk.models.v1.materials.MaterialRenameParams;

// The rename method takes a params object with builder
client.v1().materials().rename(
    MaterialRenameParams.builder()
        .id("mat_123abc")
        .name("New Material Name")
        .build()
);

System.out.println("Material renamed successfully");

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.Threading.Tasks;

public class RenameMaterial
{
    public static async Task Rename()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var renamedMaterial = await client.V1.Materials.Rename(new()
        {
            ID = "mat_123abc",
            Name = "Biology Chapter 2 - Updated"
        });

        Console.WriteLine($"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.

JavaScript

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

Python

updated_material = client.v1.materials.update(
    material_id="mat_123abc",
    references=[
        {
            "title": "Introduction to Biology, 3rd Edition",
            "url": "https://example.com/biology-textbook"
        }
    ]
)

print(f"Material updated: {updated_material._id}")

Java

import com.studyfetch.javasdk.models.v1.materials.MaterialUpdateParams;
import com.studyfetch.javasdk.models.v1.materials.Reference;
import java.util.List;

MaterialResponse updatedMaterial = client.v1().materials().update(
    MaterialUpdateParams.builder()
        .id("mat_123abc")
        .references(List.of(
            Reference.builder()
                .title("Introduction to Biology, 3rd Edition")
                .url("https://example.com/biology-textbook")
                .build()
        ))
        .build()
);

System.out.println("Material updated: " + updatedMaterial._id());

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using StudyfetchSDK.Models.V1.Materials.MaterialUpdateParamsProperties;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class UpdateMaterialReference
{
    public static async Task UpdateReference()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Update material references
        var updatedMaterial = await client.V1.Materials.Update(new()
        {
            ID = "mat_123abc",
            References = new List<StudyfetchSDK.Models.V1.Materials.MaterialUpdateParamsProperties.Reference>
            {
                new() { Title = "Updated Reference", URL = "https://example.com/updated" },
                new() { Title = "New Reference", URL = "https://example.com/new" }
            }
        });

        Console.WriteLine($"Material updated: {updatedMaterial._ID}");

        // Alternative: Create a new material with references
        var materialWithReferences = await client.V1.Materials.Create(new()
        {
            Name = "Biology Material with References",
            Content = new()
            {
                Type = StudyfetchSDK.Models.V1.Materials.ContentProperties.Type.Text,
                Text = "Material content with source citations"
            },
            References = new List<StudyfetchSDK.Models.V1.Materials.Reference>
            {
                new("Introduction to Biology, 3rd Edition")
                {
                    URL = "https://example.com/biology-textbook"
                }
            }
        });

        Console.WriteLine($"Material created with references: {materialWithReferences._ID}");
    }
}

Delete Material

Permanently delete a material. This is a soft delete - the material is marked as deleted but retained for audit purposes.

JavaScript

await client.v1.materials.delete('mat_123abc');

console.log('Material deleted successfully');

Python

client.v1.materials.delete("mat_123abc")

print("Material deleted successfully")

Java

import com.studyfetch.javasdk.models.v1.materials.MaterialDeleteParams;

// Delete material by ID
client.v1().materials().delete(
    MaterialDeleteParams.builder()
        .id("mat_123abc")
        .build()
);

System.out.println("Material deleted successfully");

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.Threading.Tasks;

public class DeleteMaterial
{
    public static async Task Delete()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        await client.V1.Materials.Delete(new()
        {
            ID = "mat_123abc"
        });

        Console.WriteLine("Material deleted successfully");
    }
}

Bulk Move Materials

Move multiple materials to a folder in a single operation.

JavaScript

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

Python

material_ids = ["mat_123abc", "mat_456def", "mat_789ghi"]

result = client.v1.materials.bulk.move({
    'materialIds': material_ids,
    'folderId': "folder_999xyz"
})

print(f"Moved {result['movedCount']} materials")

Java

import com.studyfetch.javasdk.models.v1.materials.bulk.BulkMoveParams;
import java.util.Arrays;
import java.util.List;

List<String> materialIds = Arrays.asList(
    "mat_123abc", 
    "mat_456def", 
    "mat_789ghi"
);

BulkMoveParams params = BulkMoveParams.builder()
    .materialIds(materialIds)
    .folderId("folder_999xyz")
    .build();

client.v1().materials().bulk().move(params);

System.out.println("Materials moved successfully");

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials.Bulk;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class BulkMoveMaterials
{
    public static async Task BulkMove()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        var materialIds = new List<string> { "mat_123abc", "mat_456def", "mat_789ghi" };

        var result = await client.V1.Materials.Bulk.Move(new()
        {
            MaterialIDs = materialIds,
            FolderID = "folder_999xyz"
        });

        Console.WriteLine($"Moved {result.MovedCount} materials");
    }
}

Download Material

Get a temporary download URL for a material stored in S3.

JavaScript

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

Python

# Get download URL (expires in 1 hour by default)
download_info = client.v1.materials.get_download_url("mat_123abc", {
    'expiresIn': '3600'
})

# Get download URL with custom expiry (in seconds)
custom_info = client.v1.materials.get_download_url("mat_123abc", {
    'expiresIn': '7200'  # 2 hours
})

print(f"Download URL: {download_info['downloadUrl']}")

Java

import com.studyfetch.javasdk.models.v1.materials.MaterialGetDownloadUrlParams;

// Get download URL (expires in 1 hour by default)
MaterialGetDownloadUrlParams params = MaterialGetDownloadUrlParams.builder()
    .id("mat_123abc")
    .expiresIn(3600)
    .build();
client.v1().materials().getDownloadUrl(params);

// Get download URL with custom expiry (in seconds)
MaterialGetDownloadUrlParams customParams = MaterialGetDownloadUrlParams.builder()
    .id("mat_123abc")
    .expiresIn(7200) // 2 hours
    .build();
client.v1().materials().getDownloadUrl(customParams);

System.out.println("Download URL retrieved successfully");

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.Threading.Tasks;

public class DownloadMaterial
{
    public static async Task GetDownloadUrl()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // Get download URL (expires in 1 hour by default)
        var downloadInfo = await client.V1.Materials.GetDownloadURL(new()
        {
            ID = "mat_123abc"
        });

        // Get download URL with custom expiry (in seconds)
        var customInfo = await client.V1.Materials.GetDownloadURL(new()
        {
            ID = "mat_123abc"
        });

        Console.WriteLine($"Download URL: {downloadInfo.DownloadURL}");
    }
}

Example: Complete Material Management Flow

Here's a complete example showing the typical lifecycle of material management:

JavaScript

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

Python

import time

# 1. Upload a material
with open('biology-notes.pdf', 'rb') as file:
    material = client.v1.materials.upload(
        file=file,
        name="Biology Notes v1"
    )
print(f"Uploaded: {material._id}")

# 2. Wait for processing
status = "processing"
while status == "processing":
    time.sleep(2)
    updated = client.v1.materials.retrieve(material._id)
    status = updated.status

# 3. Rename the material
renamed = client.v1.materials.rename(
    material_id=material._id,
    name="Biology Notes - Final Version"
)

# 4. Move to a folder
moved = client.v1.materials.move(
    material_id=material._id,
    folder_id="folder_biology"
)

# 5. Get download URL
download_info = client.v1.materials.get_download_url(material._id, {
    'expiresIn': '3600'
})
print(f"Download from: {download_info['downloadUrl']}")

# 6. Eventually delete
# client.v1.materials.delete(material._id)

Java

import com.studyfetch.javasdk.models.v1.materials.upload.UploadUploadFileParams;
import com.studyfetch.javasdk.models.v1.materials.MaterialResponse;
import com.studyfetch.javasdk.models.v1.materials.MaterialRetrieveParams;
import com.studyfetch.javasdk.models.v1.materials.MaterialRenameParams;
import com.studyfetch.javasdk.models.v1.materials.MaterialMoveParams;
import com.studyfetch.javasdk.models.v1.materials.MaterialGetDownloadUrlParams;
import com.studyfetch.javasdk.models.v1.materials.MaterialDeleteParams;
import java.io.File;
import java.io.FileInputStream;

// 1. Upload a material
File file = new File("biology-notes.pdf");
UploadUploadFileParams uploadParams = UploadUploadFileParams.builder()
    .file(new FileInputStream(file))
    .name("Biology Notes v1")
    .build();
MaterialResponse material = client.v1().materials().upload().uploadFile(uploadParams);
System.out.println("Uploaded: " + material._id());

// 2. Wait for processing
MaterialResponse.Status status = MaterialResponse.Status.PROCESSING;
while (status.equals(MaterialResponse.Status.PROCESSING)) {
    Thread.sleep(2000);
    MaterialResponse updated = client.v1().materials().retrieve(
        MaterialRetrieveParams.builder()
            .id(material._id())
            .build()
    );
    status = updated.status();
}

// 3. Rename the material
client.v1().materials().rename(
    MaterialRenameParams.builder()
        .id(material._id())
        .name("Biology Notes v2")
        .build()
);

// 4. Move to a folder
client.v1().materials().move(
    MaterialMoveParams.builder()
        .id(material._id())
        .folderId("folder_456def")
        .build()
);

// 5. Get download URL
MaterialGetDownloadUrlParams downloadParams = MaterialGetDownloadUrlParams.builder()
    .id(material._id())
    .expiresIn(3600)
    .build();
client.v1().materials().getDownloadUrl(downloadParams);

// 6. Eventually delete
// client.v1().materials().delete(
//     MaterialDeleteParams.builder()
//         .id(material._id())
//         .build()
// );

C#

using StudyfetchSDK;
using StudyfetchSDK.Models.V1.Materials;
using System;
using System.IO;
using System.Threading.Tasks;

public class CompleteMaterialManagementFlow
{
    public static async Task ManageMaterial()
    {
        var client = new StudyfetchSDKClient()
        {
            APIKey = Environment.GetEnvironmentVariable("STUDYFETCH_API_KEY"),
            BaseUrl = new Uri("https://studyfetchapi.com")
        };

        // 1. Upload a material
        var fileBytes = await File.ReadAllBytesAsync("biology-notes.pdf");
        var material = await client.V1.Materials.Upload.UploadFile(new()
        {
            File = fileBytes,
            FileName = "biology-notes.pdf",
            Name = "Biology Notes v1"
        });
        Console.WriteLine($"Uploaded: {material._ID}");

        // 2. Wait for processing
        var status = "processing";
        while (status == "processing")
        {
            await Task.Delay(2000);
            var updated = await client.V1.Materials.Retrieve(new()
            {
                ID = material._ID
            });
            status = updated.Status.Raw();
        }

        // 3. Rename the material
        var renamed = await client.V1.Materials.Rename(new()
        {
            ID = material._ID,
            Name = "Biology Notes - Final Version"
        });

        // 4. Move to a folder
        var moved = await client.V1.Materials.Move(new()
        {
            ID = material._ID,
            FolderID = "folder_biology"
        });

        // 5. Get download URL
        var downloadInfo = await client.V1.Materials.GetDownloadURL(new()
        {
            ID = material._ID
        });
        Console.WriteLine($"Download from: {downloadInfo.DownloadURL}");

        // 6. Eventually delete
        // await client.V1.Materials.Delete(new() { ID = material._ID });
    }
}
PreviousGenerating MaterialsNextSearch