Assets API reference
Upload images and files to Content Lake, and link Media Library assets to your dataset.
Use the Assets API to upload images and files to a Content Lake dataset. Send the file as the request body, or give a URL for Sanity to fetch. Each upload stores the file and creates a sanity.imageAsset or sanity.fileAsset document that image and file fields can reference.
To use an asset from your organization's Media Library, link it to a dataset with the media-library-link endpoint. To upload and manage assets in Media Library itself, use the Media Library API.
Asset documents are regular documents. To edit an asset's metadata or delete an asset, use the Mutation API. Learn more in Upload, query, and delete assets.
In JavaScript, client.assets.upload() in @sanity/client wraps the upload endpoints. The client has no helper for uploading from a URL or linking Media Library assets, so call those endpoints with client.request(). Learn more in Working with assets in @sanity/client.
Authentication
All requests must be authenticated.
Uploading requires permission to create documents in the dataset. Linking a Media Library asset also requires read access to the asset in Media Library and a token for a Sanity user. Robot tokens are rejected.
Base API server URL
Assets API base URL
https://{projectId}.api.sanity.io/{apiVersion}/assetsVariables
- apiVersionstringdefault:
"v2024-06-24"API version
- projectIdstringdefault:
"your-project-id"Sanity project ID
Endpoints
Upload an image asset
/images/{dataset}Upload an image asset to Content Lake.
This uploads an image and creates a linked sanity.imageAsset document containing the image metadata.
Path parameters
Query parameters
- filenamestring
Filename for this file (optional)
- titlestring
Optional title for the asset
- descriptionstring
Optional description for the asset
Array of metadata to extract from asset
items
- itemsstring
- labelstring
Optional freeform label for the asset.
- tagstring
Optional request tag for the upload. Learn more in the request tag documentation.
- creditLinestring
The credit to people or organizations required by the supplier of the asset to be used when published.
- sourceNamestring
The name of the source if the asset is from an external service. Requires
sourceId. - sourceIdstring
The ID of the asset within the external source. Required when
sourceNameis set, and ignored without it. - sourceUrlstring
The URL of the asset within the external source. Ignored without
sourceName.
Request body image/*
- string (binary)
The image file to upload.
Responses
Upload successful
- documentobject
Show child attributes
- _idstring
- _typestringExample:
sanity.imageAsset - _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)
The CDN URL of the asset
Example:https://cdn.sanity.io/images/myproject/mydataset/cd6b7eaf68c33e65ee6866873b9c0e48be84bb01-500x400.jpg - pathstring
- sizenumber
Size of the asset in bytes.
Example:202546 - mimeTypestring
MIME type of the asset.
Example:image/jpeg - assetIdstring
- extensionstringExample:
jpg - originalFilenamestringExample:
my-image.jpg - sha1hashstringExample:
cd6b7eaf68c33e65ee6866873b9c0e48be84bb01 - metadataobject
Metadata extracted from the asset. Learn more in the metadata documentation.
Show child attributes
- _typestringExample:
sanity.imageMetadata - dimensionsobject
Show child attributes
- _typestringExample:
sanity.imageDimensions - widthnumberExample:
500 - heightnumberExample:
400 - aspectRationumberExample:
1.25
Invalid request, such as a parameter that fails validation, an empty body, an unsupported image type (Unsupported image type), or an image whose metadata can't be read.
Unauthorized. The token is missing a valid session, for example Session not found.
Payment required. A usage limit blocks asset uploads for this project. The response body's error and message fields give the reason.
Forbidden. The request has no token, or the token lacks the create permission in the dataset. The body is a mutationError with an insufficientPermissionsError item.
The image could not be processed. The message is Invalid image, could not process.
Rate limit exceeded for writes to this asset, with the message Rate limit exceeded for mutations to this asset. This happens when the same file is uploaded repeatedly in a short time. Wait before uploading it again.
Temporarily unavailable, for example because of a storage rate limit or an image processing timeout. Try again.
Upload a file asset
/files/{dataset}Upload a file asset to Content Lake.
This uploads a file and creates a linked sanity.fileAsset document containing the file metadata.
The asset's mimeType is taken from the request's Content-Type header. Set filename to keep the original extension.
Path parameters
Query parameters
- filenamestring
Filename for this file (optional)
- titlestring
Optional title for the asset
- descriptionstring
Optional description for the asset
- labelstring
Optional freeform label for the asset.
- tagstring
Optional request tag for the upload. Learn more in the request tag documentation.
- creditLinestring
The credit to people or organizations required by the supplier of the asset to be used when published.
- sourceNamestring
The name of the source if the asset is from an external service. Requires
sourceId. - sourceIdstring
The ID of the asset within the external source. Required when
sourceNameis set, and ignored without it. - sourceUrlstring
The URL of the asset within the external source. Ignored without
sourceName.
Request body */*
- string (binary)
The file binary to upload.
Responses
Upload successful
- documentobject
Show child attributes
- _idstring
- _typestringExample:
sanity.fileAsset - _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)Example:
https://cdn.sanity.io/files/myproject/mydataset/cd6b7eaf68c33e65ee6866873b9c0e48be84bb01.pdf - pathstring
- sizenumber
Size of the asset in bytes.
Example:202546 - mimeTypestring
MIME type of the asset.
Example:image/jpeg - assetIdstring
- extensionstringExample:
jpg - originalFilenamestringExample:
my-image.jpg - sha1hashstringExample:
cd6b7eaf68c33e65ee6866873b9c0e48be84bb01
Invalid request, such as a parameter that fails validation or an empty body.
Unauthorized. The token is missing a valid session, for example Session not found.
Payment required. A usage limit blocks asset uploads for this project. The response body's error and message fields give the reason.
Forbidden. The request has no token, or the token lacks the create permission in the dataset. The body is a mutationError with an insufficientPermissionsError item.
Rate limit exceeded for writes to this asset, with the message Rate limit exceeded for mutations to this asset. This happens when the same file is uploaded repeatedly in a short time. Wait before uploading it again.
Temporarily unavailable, for example because of a storage rate limit or an image processing timeout. Try again.
Upload an image asset from a URL
/images/{dataset}/from-urlUpload an image asset from a public or preauthorized HTTPS URL and create a sanity.imageAsset document in Content Lake.
Sanity fetches the source without forwarding your API token, cookies, or request headers. The source and each redirect destination must use HTTPS without embedded credentials and pass the source policy. Up to three redirects are followed. The source is limited to 50 MiB (52,428,800 bytes), and fetching may take up to 300 seconds. The JSON request body is limited to 4 KiB.
Provide filename in the JSON body; the filename query parameter is not accepted. The other upload metadata parameters work as on the ordinary upload endpoint. Provide sourceName and sourceId together; sourceUrl is attribution metadata, not the URL to fetch.
Allow more than 300 seconds for the client request. If the connection closes or the request times out, check the dataset before retrying: the asset may already have been created. Use the returned document._id as the asset reference in an image or file field.
Path parameters
Query parameters
- titlestring
Optional title for the asset
- descriptionstring
Optional description for the asset
Image metadata to extract. Repeat the parameter for multiple values, such as meta=palette&meta=lqip.
items
- itemsstring
- labelstring
Optional freeform label for the asset.
- tagstring
Optional request tag for the upload. Learn more in the request tag documentation.
- creditLinestring
The credit to people or organizations required by the supplier of the asset to be used when published.
- sourceNamestring
The name of the source if the asset is from an external service. Requires
sourceId. - sourceIdstring
The ID of the asset within the external source. Required when
sourceNameis set, and ignored without it. - sourceUrlstring
The URL of the asset within the external source. Ignored without
sourceName.
Request body application/json
Public or preauthorized HTTPS URL returning the asset bytes. URLs with embedded usernames or passwords are not supported.
- filenamestring
Optional original filename, including the extension. Must not contain path separators or a null character.
application/json{
"url": "https://example.com/chair.jpg",
"filename": "chair.jpg"
}Responses
Upload successful
- documentobject
Show child attributes
- _idstring
- _typestringExample:
sanity.imageAsset - _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)
The CDN URL of the asset
Example:https://cdn.sanity.io/images/myproject/mydataset/cd6b7eaf68c33e65ee6866873b9c0e48be84bb01-500x400.jpg - pathstring
- sizenumber
Size of the asset in bytes.
Example:202546 - mimeTypestring
MIME type of the asset.
Example:image/jpeg - assetIdstring
- extensionstringExample:
jpg - originalFilenamestringExample:
my-image.jpg - sha1hashstringExample:
cd6b7eaf68c33e65ee6866873b9c0e48be84bb01 - metadataobject
Metadata extracted from the asset. Learn more in the metadata documentation.
Show child attributes
- _typestringExample:
sanity.imageMetadata - dimensionsobject
Show child attributes
- _typestringExample:
sanity.imageDimensions - widthnumberExample:
500 - heightnumberExample:
400 - aspectRationumberExample:
1.25
Invalid request or source URL, blocked destination, redirect limit exceeded, empty or unsupported source content, or the source returned a 4xx status other than 408, 425, or 429. Check that the URL returns asset bytes without additional authentication.
Unauthorized. Also returned with the message Session expires too soon for asset URL ingestion. Please retry. when the session for the request expires in less than 390 seconds.
Payment required. A usage limit blocks asset uploads for this project. The response body's error and message fields give the reason.
Forbidden. The request has no token, or the token lacks the create permission in the dataset. The body is a mutationError with an insufficientPermissionsError item.
Source exceeds 50 MiB or the JSON request body exceeds 4 KiB.
The image could not be processed. The message is Invalid image, could not process.
Rate limit exceeded for writes to this asset, with the message Rate limit exceeded for mutations to this asset. This happens when the same file is uploaded repeatedly in a short time. Wait before uploading it again.
Source could not be fetched, or returned a server error or a transient status (408, 425, or 429). Check that the URL is reachable and try again.
Temporarily unavailable, for example because of a storage rate limit or an image processing timeout. Try again.
Source fetch or gateway request timed out. Check the dataset before retrying.
Upload a file asset from a URL
/files/{dataset}/from-urlUpload a file asset from a public or preauthorized HTTPS URL and create a sanity.fileAsset document in Content Lake.
The source's Content-Type header is not used. The asset's mimeType and extension come from filename or from the file content, so provide filename to get the right type.
Sanity fetches the source without forwarding your API token, cookies, or request headers. The source and each redirect destination must use HTTPS without embedded credentials and pass the source policy. Up to three redirects are followed. The source is limited to 50 MiB (52,428,800 bytes), and fetching may take up to 300 seconds. The JSON request body is limited to 4 KiB.
Provide filename in the JSON body; the filename query parameter is not accepted. The other upload metadata parameters work as on the ordinary upload endpoint. Provide sourceName and sourceId together; sourceUrl is attribution metadata, not the URL to fetch.
Allow more than 300 seconds for the client request. If the connection closes or the request times out, check the dataset before retrying: the asset may already have been created. Use the returned document._id as the asset reference in an image or file field.
Path parameters
Query parameters
- titlestring
Optional title for the asset
- descriptionstring
Optional description for the asset
- labelstring
Optional freeform label for the asset.
- tagstring
Optional request tag for the upload. Learn more in the request tag documentation.
- creditLinestring
The credit to people or organizations required by the supplier of the asset to be used when published.
- sourceNamestring
The name of the source if the asset is from an external service. Requires
sourceId. - sourceIdstring
The ID of the asset within the external source. Required when
sourceNameis set, and ignored without it. - sourceUrlstring
The URL of the asset within the external source. Ignored without
sourceName.
Request body application/json
Public or preauthorized HTTPS URL returning the asset bytes. URLs with embedded usernames or passwords are not supported.
- filenamestring
Optional original filename, including the extension. Must not contain path separators or a null character.
application/json{
"url": "https://example.com/manual.pdf",
"filename": "manual.pdf"
}Responses
Upload successful
- documentobject
Show child attributes
- _idstring
- _typestringExample:
sanity.fileAsset - _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)Example:
https://cdn.sanity.io/files/myproject/mydataset/cd6b7eaf68c33e65ee6866873b9c0e48be84bb01.pdf - pathstring
- sizenumber
Size of the asset in bytes.
Example:202546 - mimeTypestring
MIME type of the asset.
Example:image/jpeg - assetIdstring
- extensionstringExample:
jpg - originalFilenamestringExample:
my-image.jpg - sha1hashstringExample:
cd6b7eaf68c33e65ee6866873b9c0e48be84bb01
Invalid request or source URL, blocked destination, redirect limit exceeded, empty or unsupported source content, or the source returned a 4xx status other than 408, 425, or 429. Check that the URL returns asset bytes without additional authentication.
Unauthorized. Also returned with the message Session expires too soon for asset URL ingestion. Please retry. when the session for the request expires in less than 390 seconds.
Payment required. A usage limit blocks asset uploads for this project. The response body's error and message fields give the reason.
Forbidden. The request has no token, or the token lacks the create permission in the dataset. The body is a mutationError with an insufficientPermissionsError item.
Source exceeds 50 MiB or the JSON request body exceeds 4 KiB.
Rate limit exceeded for writes to this asset, with the message Rate limit exceeded for mutations to this asset. This happens when the same file is uploaded repeatedly in a short time. Wait before uploading it again.
Source could not be fetched, or returned a server error or a transient status (408, 425, or 429). Check that the URL is reachable and try again.
Temporarily unavailable, for example because of a storage rate limit or an image processing timeout. Try again.
Source fetch or gateway request timed out. Check the dataset before retrying.
Link a Media Library asset to a dataset
/media-library-link/{dataset}Creates a linked Media Library asset in your dataset. To support features like preview, Media Library assets need to be linked to a local asset document. Pair with the Mutation API to attach linked Media Library assets to documents. Requires a token for a Sanity user. Robot tokens are rejected.
Path parameters
Query parameters
Image metadata to copy from the Media Library asset to the linked asset document. Applies to image assets only.
dimensions,hasAlpha, andisOpaqueare always included. Repeat the parameter for multiple values, such as meta=palette&meta=lqip.items
- itemsstring
Request body application/json
The asset ID of the Media Library asset. This comes from the
asset._idfield returned as part of the response when uploading an asset to the library.The ID of the Media Library.
The asset instance ID of the Media Library asset. This comes from the
assetInstance._idfield returned as part of the response when uploading an asset to the library.
Responses
Link created successfully
The linked asset document in your dataset. Its
_typeissanity.imageAsset,sanity.fileAsset, orsanity.videoAsset.Show child attributes
- _idstring
- _typestringExample:
sanity.imageAsset - _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)
The CDN URL of the asset
Example:https://cdn.sanity.io/images/myproject/mydataset/cd6b7eaf68c33e65ee6866873b9c0e48be84bb01-500x400.jpg - pathstring
- sizenumber
Size of the asset in bytes.
Example:202546 - mimeTypestring
MIME type of the asset.
Example:image/jpeg - assetIdstring
- extensionstringExample:
jpg - originalFilenamestringExample:
my-image.jpg - sha1hashstringExample:
cd6b7eaf68c33e65ee6866873b9c0e48be84bb01 - metadataobject
Metadata extracted from the asset. Learn more in the metadata documentation.
Show child attributes
- _typestringExample:
sanity.imageMetadata - dimensionsobject
Show child attributes
- _typestringExample:
sanity.imageDimensions - widthnumberExample:
500 - heightnumberExample:
400 - aspectRationumberExample:
1.25
- _idstring
- _typestringExample:
sanity.fileAsset - _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)Example:
https://cdn.sanity.io/files/myproject/mydataset/cd6b7eaf68c33e65ee6866873b9c0e48be84bb01.pdf - pathstring
- sizenumber
Size of the asset in bytes.
Example:202546 - mimeTypestring
MIME type of the asset.
Example:image/jpeg - assetIdstring
- extensionstringExample:
jpg - originalFilenamestringExample:
my-image.jpg - sha1hashstringExample:
cd6b7eaf68c33e65ee6866873b9c0e48be84bb01
- _idstring
- _typestring
- _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
Invalid request
Unauthorized. Also returned with the message Invalid non-global session for user id <id> when the request uses a robot token.
Forbidden. The message is Could not access media library asset when you can't read the asset in the Media Library. Also returned when the token lacks the create permission in the dataset.
The Media Library asset was not found. The message starts with Asset not found, or is Media library asset not found when the stored file is missing.
The Media Library asset can't be linked. The message is Media library asset is not ready for a video that is still processing, or Asset instance does not belong to asset container when assetInstanceId doesn't belong to assetId.