Folders

Organize Media Library assets into a navigable hierarchy with folders.

A folder hierarchy in Media Library is made up of three document types from the Content Lake hierarchy primitive: sanity.tree, sanity.directory, and sanity.symlink.

Assets (sanity.asset) sit inside folders by carrying a parent reference to a sanity.directory.

These examples use @sanity/client configured against your Media Library. They also work via the standard Media Library mutate and query endpoints.

Every folder hierarchy starts with one sanity.tree document.

import {createClient} from '@sanity/client'

const libraryId = '<your-library-id>'

const client = createClient({
  apiVersion: '2025-02-19',
  resource: {type: 'media-library', id: libraryId},
  token: process.env.SANITY_TOKEN,
})

await client.createIfNotExists({
  _id: `tree.${libraryId}`,
  _type: 'sanity.tree',
  name: 'folders',
})

const libraryId = '<your-library-id>'
const token = '<personal-auth-token>'

await fetch(`https://api.sanity.io/v2025-02-19/media-libraries/${libraryId}/mutate`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    mutations: [
      {
        createIfNotExists: {
          _id: `tree.${libraryId}`,
          _type: 'sanity.tree',
          name: 'folders',
        },
      },
    ],
  }),
})

Create a sanity.directory with a name and a parent reference. Top-level folders point at the tree; nested folders point at their parent directory.

// Use the same `tree.${libraryId}` ID created in Step 1
const treeId = `tree.${libraryId}`

// Top-level folder
const marketing = await client.create({
  _type: 'sanity.directory',
  name: 'Marketing',
  parent: {_ref: treeId},
})

// Nested folder
const campaigns = await client.create({
  _type: 'sanity.directory',
  name: 'Campaigns',
  parent: {_ref: marketing._id},
})

For directory creation patterns, validation rules, and the error reference, see Creating directories in the hierarchy primitive.

For assets that are already uploaded, set parent on the sanity.asset document to move it into a folder.

await client
  .patch(asset._id)
  .set({parent: {_ref: folderId}})
  .commit()

When uploading a new asset, set the parent query parameter on the upload endpoint to place it in a folder in a single request, no follow-up patch needed.

For the full upload pattern, see Upload assets programmatically.

Media Library hierarchy is queried with standard GROQ. The same patterns documented in Querying the hierarchy apply

You can query assets inside a specific folder with:

*[_type == "sanity.asset" && parent._ref == $folderId]

Patch parent to a new destination. The server validates the destination before any change is applied, see the error reference.

await client
  .patch(folderToMove._id)
  .set({parent: {_ref: newParentId}})
  .commit()

The same pattern applies to assets. Set parent to move an asset into a different folder, or unset it to remove the asset from any folder.

A shortcut makes a single asset visible inside an additional folder without duplicating the underlying file. Shortcuts are sanity.symlink documents that reference a destination folder via parent and an asset via target.

await client.create({
  _type: 'sanity.symlink',
  parent: {_ref: destinationFolderId},
  target: {_ref: assetId},
})

await client.delete(folderId)

In the Media Library app, the delete folder action handles this for you. It deletes children recursively and displays a confirmation dialog that surfaces information about contents and potential warnings. See Deleting folders in the interface.