Link assets to documents
Linking an asset in the Media Library to a document in your project requires a few extra steps.
When editors use Sanity Studio to add assets to documents, the studio and Media Library work together to link the project, document, and library. To do this programmatically, like when migrating a large number of assets to your library, you'll need to perform the steps manually.
Rendering assets
This guide is specifically about programmatically linking assets from Media Library to documents in your datasets. For details on rendering assets, check out the Presenting images guide.
In this guide, you'll learn how to link Media Library assets to documents in a project dataset. There are three key steps:
- Upload the asset to Media Library, or query an existing asset in Media Library to obtain the necessary IDs.
- Link the Media Library asset to your project dataset.
- Patch any documents that use the asset with the correct references.
Prerequisites:
- An environment where you can make HTTP requests. The code examples use
fetchin Node.js, which was made stable in v21.0. You can substitute any request library and any language. - Project and library identifiers:
mediaLibraryIdfrom your Media Library.projectIdfor the project you want to link the assets to.datasetfor the project you want to link the assets to.
- A personal authentication token with permission to read/write from both the Media Library and your project. The examples read the token from the
SANITY_API_TOKENenvironment variable. - An API version of
2025-02-19or later. Global document references, which link Media Library assets to documents in a dataset, aren't supported on earlier versions. The examples in this guide usev2025-02-19in their request URLs.
Gather the asset IDs
Linking a Media Library asset requires two identifiers:
- Asset ID: The primary identifier (
_id) for an asset document in your Media Library. - Asset instance ID: The identifier for a versioned instance of the asset. An asset can have several versions.
currentVersionpoints to the active instance.
There are two ways to obtain these values.
Get IDs during upload
After uploading an asset with the media-libraries/upload endpoint, the response contains asset._id and assetInstance._id. For details on using the API to upload assets, see the following guide.
Get IDs by querying assets
If your assets are already in Media Library, you can query the Media Library API for asset documents. If you already know the Asset ID, you can query it directly with the _id == '<asset-id>' GROQ filter. If you don't know the ID(s), you can query all assets with _type == 'sanity.asset'.
For example, this query returns all asset documents in the library:
// Define your library ID.
const mediaLibraryId = 'MEDIA_LIBRARY_ID'
// Read your personal auth token from the environment.
const token = process.env.SANITY_API_TOKEN
// Define your query
const query = `*[_type == 'sanity.asset']`
// POST a request to the HTTP API with the query as the body
const response = await fetch(`https://api.sanity.io/v2025-02-19/media-libraries/${mediaLibraryId}/query`, {
method: 'POST',
body: JSON.stringify({query}),
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
}
})
console.log(await response.json()){
"query": "*[_type == 'sanity.asset']",
"result": [
{
"versions": [],
"_type": "sanity.asset",
"_id": "2w91UKgsNKEhWD6au6OzeNaOe7f",
"_updatedAt": "2025-04-23T20:09:54Z",
"_createdAt": "2025-04-23T20:09:49Z",
"_rev": "LR2OfQiXk5TMHKZpxdBNWd",
"aspects": {},
"title": "Silhouette of a Woman in a Doorway Overlooking the Ocean",
"currentVersion": {
"_type": "reference",
"_key": "",
"_weak": false,
"_ref": "image-11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422-jpg"
},
"assetType": "sanity.imageAsset",
"cdnAccessPolicy": "public",
"_system": {
"createdBy": "gvRshKueQ"
}
}
],
"syncTags": [],
"ms": 5
}In the example response JSON, the highlighted lines show the IDs you need.
- Asset ID: The
_idof the document. - Asset instance ID: The
currentVersion._ref.
Link the asset to your project dataset
The next step is to link the asset to your project dataset with the assets/media-library-link API. This creates a local reference point that you can use throughout the dataset. Note the _id and the media._ref in the response for the next step.
// Define your library ID, project ID, and dataset
const mediaLibraryId = 'MEDIA_LIBRARY_ID'
const projectId = 'YOUR_PROJECT_ID'
const dataset = 'YOUR_DATASET'
// Read your personal auth token from the environment.
const token = process.env.SANITY_API_TOKEN
// Define the request body based on the Asset IDs from the previous step
// We've included the IDs from the earlier output as an example.
const requestBody = {
mediaLibraryId: mediaLibraryId,
assetInstanceId: "image-11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422-jpg",
assetId: "2w91UKgsNKEhWD6au6OzeNaOe7f"
}
// POST a request to the assets API
const response = await fetch(`https://${projectId}.api.sanity.io/v2025-02-19/assets/media-library-link/${dataset}`, {
method: 'POST',
body: JSON.stringify(requestBody),
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
}
})
console.log(await response.json()){
"document": {
"_createdAt": "2025-04-23T22:01:54Z",
"_id": "image-11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422-jpg",
"_rev": "DkN0DBPn76SUp7SIvfkLE9",
"_type": "sanity.imageAsset",
"_updatedAt": "2025-04-23T22:01:54Z",
"assetId": "11736fa2881515ae4fb5ba3db2fc247778ce8fab",
"extension": "jpg",
"media": {
"_ref": "media-library:mlNBkjZ8wqSZ:2w91UKgsNKEhWD6au6OzeNaOe7f",
"_type": "reference",
"_weak": true
},
"metadata": {},
"mimeType": "image/jpeg",
"originalFilename": "11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422.jpg",
"path": "images/y856rro4/production/11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422.jpg",
"sha1hash": "11736fa2881515ae4fb5ba3db2fc247778ce8fab",
"size": 4763977,
"uploadId": "ml-link-Sg56SH3Sncz1on2HW9jvecXRdNC4mSWJ",
"url": "https://cdn.sanity.io/images/y856rro4/production/11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422.jpg"
}
}If you link an asset immediately after uploading it, the request can fail with status 422 and the message Media library asset is not ready while Media Library finishes processing the asset. Wait a few seconds, then retry the request.
Patch the documents
Now that the asset is linked to your project and dataset, you can attach it to documents with a document mutation.
Use the document ID and the media reference from the previous step to attach the asset to documents in your dataset. As with local assets, you can patch linked Media Library assets to a document. The key difference is that you need to update the asset and media objects.
This example adds the asset to a poster field on the target document. Replace the path to the asset and media to match the shape of your content.
// Define your project ID and dataset
const projectId = 'YOUR_PROJECT_ID'
const dataset = 'YOUR_DATASET'
// Read your personal auth token from the environment.
const token = process.env.SANITY_API_TOKEN
// Define the ID of the target document
const documentId = 'TARGET_DOCUMENT_ID'
// Define the asset document ID and the media reference
// from the previous step
const assetDocumentId = 'image-11736fa2881515ae4fb5ba3db2fc247778ce8fab-4948x7422-jpg'
const mediaRef = 'media-library:mlNBkjZ8wqSZ:2w91UKgsNKEhWD6au6OzeNaOe7f'
// Define the mutation
const mutations = [{
patch: {
id: documentId,
set: {
poster: {
asset: {
_type: 'reference',
_ref: assetDocumentId,
},
media: {
_type: 'globalDocumentReference',
_ref: mediaRef,
_weak: true,
}
}
}
}
}]
// POST a request to the mutate API
const response = await fetch(`https://${projectId}.api.sanity.io/v2025-02-19/data/mutate/${dataset}`, {
method: 'POST',
body: JSON.stringify({mutations}),
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
}
})
console.log(await response.json())Writes that add the reference need the same API version
Any write that adds a Media Library reference to a document, including creating a draft, publishing, or duplicating a document that holds one, needs an API version of 2025-02-19 or later. Earlier versions fail with transaction failed: global document references are not supported: media-library:<mediaLibraryId>, and the client's skipCrossDatasetReferenceValidation option doesn't bypass the check.
You captured the media._ref in the previous step, but you can also build it by combining the resource type (media-library) with your library ID and the asset ID, separated by colons: media-library:MEDIA_LIBRARY_ID:ASSET_ID.
These same steps apply for linking Media Library assets to any documents.