Strapi File Management — Folders, Replace Files, and Media Library API

In this tutorial, you will learn advanced file management in Strapi's Media Library — including folder organization for structured storage, replacing files while preserving their URLs, and using the Media Library API to manage files programmatically.

What You'll Learn

• How to organize files with folders and nested folder structures
• How to replace existing files while preserving the URL
• How to use the Media Library API to search, update, and delete files
• How to manage file metadata (alternative text, captions)
• How to handle file versioning and history
• Best practices for Media Library organization at scale

Why It Matters

As your Strapi project grows, so does your Media Library. Without proper organization, finding specific files becomes impossible. Without file replacement capabilities, updating an image means uploading a new file and updating every reference. Mastering file management keeps your media collection organized, maintainable, and efficient to work with.

Real-World Use

A news site publishes 50 articles per day, each with 2-3 images. After 6 months, the Media Library has 30,000 files. Without folders, finding a specific image is like finding a needle in a haystack. With folders organized by year/month/article, editors can navigate to the correct folder in seconds. When a hero image needs updating (same article, new photo), file replacement keeps the URL unchanged, so all existing article links continue to work.

Learning Path

flowchart LR
  A["Image Optimization"] --> B["File Management
-- You are here"]:::current
  B --> C["File Security"]

  classDef current fill:#4945ff,color:#fff,stroke-width:2px

Folder Organization

Folders keep your Media Library structured and navigable.

// Creating folders via admin panel:
// Media Library > Add New Folder
// Name: "2026"
// Then create subfolders inside: "January", "February", etc.

// Creating folders via API:
// POST /api/upload/folders
// Requires admin authentication
{
  "data": {
    "name": "Article Images",
    "parent": 1  // Parent folder ID (omit for root)
  }
}

// Response:
{
  "data": {
    "id": 5,
    "name": "Article Images",
    "path": "/5",
    "pathId": 5,
    "createdAt": "2026-06-28T..."
  }
}

Best practices for folder structure:

/images
  /articles
    /2026
      /01-january
      /02-february
  /authors
  /categories
  /hero-banners
/documents
  /pdfs
  /spreadsheets
/videos
  /tutorials
  /promotional

Create this structure before uploading files in bulk. Moving files between folders later is possible but takes time.

Uploading to a Specific Folder

Upload files directly to a folder:

// Via API: include folder ID in the upload request
const formData = new FormData();
formData.append("files", file);
formData.append("fileInfo", JSON.stringify({
  folder: 5,  // Folder ID
  alternativeText: "Delicious margherita pizza",
  caption: "Homemade pizza with fresh ingredients",
}));

const response = await fetch("http://localhost:1337/api/upload", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: formData,
});

In the admin panel, you can select a folder before uploading by navigating to the folder and clicking the upload button. Files are automatically placed in the current folder.

Moving Files Between Folders

Move existing files to different folders:

// Move file via API:
// PUT /api/upload/files/:id
{
  "data": {
    "folder": 10  // Target folder ID
  }
}

// Move folder via API:
// PUT /api/upload/folders/:id
{
  "data": {
    "parent": 3  // New parent folder ID
  }
}

Moving files updates their path but does not change the file URL. The file's database ID and URL remain the same.

Replacing Files

File replacement updates the file content while keeping the same URL and ID.

// Replace file via admin panel:
// 1. Click the file in Media Library
// 2. Click "Replace" button
// 3. Select new file
// 4. Confirm replacement

// Replace file via API:
// POST /api/upload?id=<file-id>
// Content-Type: multipart/form-data
const formData = new FormData();
formData.append("files", newFile);
formData.append("fileInfo", JSON.stringify({
  id: 123,  // ID of the file to replace
}));

const response = await fetch("http://localhost:1337/api/upload?id=123", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: formData,
});

Why file replacement matters: if you have an article referencing hero-banner.jpg (URL: /uploads/hero_banner_abc123.jpg), and you replace the file, the URL stays the same. All articles using that image continue to display the new image without any updates. Without replacement, you would need to upload a new file, update every content entry that references the old file, and the old file would remain as an orphan.

Media Library API

Strapi provides API endpoints for programmatic file management:

// List all files
GET /api/upload/files
// Optional: ?filters[folder]=5&populate=folder&sort=createdAt:desc

// Get a single file
GET /api/upload/files/123

// Update file metadata
PUT /api/upload/files/123
{
  "data": {
    "name": "new-filename.jpg",
    "alternativeText": "Updated description",
    "caption": "Updated caption",
  }
}

// Delete a file
DELETE /api/upload/files/123

// List folders
GET /api/upload/folders
// ?filters[parent]=null  for root folders
// ?filters[parent]=5     for subfolders

// Get a single folder
GET /api/upload/folders/5

These endpoints require admin-level authentication. Regular user API tokens may not have access.

File Metadata Management

Each file stores metadata that can be updated:

// File metadata fields:
{
  "id": 123,
  "name": "pizza.jpg",           // Display name
  "alternativeText": "Delicious pizza with cheese and basil",  // Alt text for accessibility
  "caption": "Homemade margherita pizza",  // Caption displayed below image
  "width": 1920,
  "height": 1080,
  "formats": { /* responsive formats */ },
  "hash": "pizza_abc123",        // Unique hash from original name
  "ext": ".jpg",
  "mime": "image/jpeg",
  "size": 2048576,               // Size in bytes
  "url": "/uploads/pizza_abc123.jpg",
  "folder": { /* folder object */ },
  "related": [ /* content entries using this file */ ]
}

Always set alternativeText for Accessibility Compliance. Search engines also use alt text for image search ranking.

Finding Related Content

The Media Library shows which content entries reference a file:

// File detail in admin panel shows "Used in" section
// Lists all entries that reference this file

// Via API, populate the related field:
GET /api/upload/files/123?populate=related

// Response includes the related entries:
{
  "data": {
    "id": 123,
    "attributes": {
      "name": "pizza.jpg",
      "related": [
        { "__type": "api::article.article", "id": 5 },
        { "__type": "api::recipe.recipe", "id": 12 }
      ]
    }
  }
}

This is useful before deleting a file — you can see which content entries will lose their image.

Bulk Operations

For large Media Libraries, batch operations save time:

// Bulk delete files (via admin panel):
// 1. Select multiple files with checkboxes
// 2. Click "Delete" button
// 3. Confirm deletion

// Bulk move files (via admin panel):
// 1. Select multiple files
// 2. Click "Move" button
// 3. Select target folder

// Strapi does not have a built-in bulk API endpoint.
// For programmatic bulk operations, loop through individual API calls.

Common Mistakes

1. Not organizing files into folders from the start. A flat Media Library with thousands of files becomes unmanageable. Create a folder structure before uploading files and enforce it as a team policy.

2. Uploading duplicate files. Without checking if a file already exists, users upload the same image multiple times. Use file names or hashes to detect duplicates before uploading.

3. Deleting files that are in use. Deleting an image that is referenced by articles breaks those articles. Always check which content entries reference a file before deleting it.

4. Not updating alt text after uploading. Alt text defaults to null. Editors must manually add descriptive alt text for accessibility and SEO. Make this part of the content creation workflow.

5. Replacing a file with a different aspect ratio. Replacing an image with a different aspect ratio can break page layouts. The new file should match the dimensions of the original for consistent display.

Practice Questions

1. How do you upload a file to a specific folder in the Media Library? Answer: Include the folder ID in the fileInfo parameter when calling POST /api/upload. Or navigate to the folder in the admin panel before uploading.

2. Why is file replacement better than deleting and re-uploading? Answer: File replacement preserves the file URL and ID. All content entries referencing the file automatically display the updated file without any changes needed. Deleting breaks existing references.

3. How do you find which content entries use a specific file? Answer: Use the populate=related parameter on GET /api/upload/files/:id. Or check the "Used in" section in the admin panel file detail view.

4. Challenge: Build a complete file management workflow: (1) Create a folder structure for a blog with years and months, (2) Upload 20 images and distribute them across the correct folders, (3) Replace 3 images with new versions, (4) Update the alt text and captions for all images using the API, (5) Find which content entries reference a specific image, (6) Write a cleanup script that identifies and deletes orphaned files (files not referenced by any content entry).

FAQ

Mini Project

Your task: Build a production-ready Media Library organization system.

1. Create a folder hierarchy for a publishing platform:
   • images/articles/{year}/{month}/
   • images/authors/
   • images/categories/
   • documents/reports/
2. Upload 30 files distributed across these folders.
3. Write a script that:
   • Lists all files in a specific folder
   • Finds files with null alt text and updates them
   • Detects and reports duplicate files (same hash)
   • Finds orphaned files (not referenced by any content entry)
4. Replace 3 key images (logo, hero banner, author photo) and verify the URLs did not change.

What's Next

Now that you understand file management, proceed to File Security to learn about signed URLs, access control for private files, and protecting uploaded files from unauthorized access. After that, explore the Plugin Ecosystem.

Related lessons:

• REST API — Upload and file endpoints
• Node.js File System — How Strapi stores files
• WordPress Media Library — Compare file management