HTTP API ReferenceLast updated January 9, 2026

Assets API reference

Upload images and files to Content Lake, and link Media Library assets to your dataset.

Use the Assets API to upload and manage assets in your Content Lake datasets. For assets stored in Media Library, use the Media Library API.

Want to get started with assets?

Assets

Sanity provides extensible UI for managing assets, and an API for dealing with storage, resizing and deletion.

Base API server URL

Assets API base URL

https://{projectId}.api.sanity.io/{apiVersion}/assets

Variables

apiVersionstringdefault: "v2024-06-24"
API version
projectIdstringdefault: "your-project-id"
Sanity project ID

Endpoints

Upload an image asset

post/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

datasetstringrequired

Query parameters

filenamestring
Filename for this file (optional)
titlestring
Optional title for the asset
descriptionstring
Optional description for the asset
metaarray
Array of metadata to extract from asset
items
- itemsstringdefault: ["palette","lqip","blurhash"]
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 person(s) and/or organization(s) required by the supplier of the asset to be used when published.
sourceNamestring
The name of the source if asset is from an external service.
sourceIdstring
Use with sourceName. The id of the asset within the external source.
sourceUrlstring
Use with sourceName. The url of the asset within the external source.

Request body `image/*`

string (binary)
The image file to upload.

Responses

Select response

200

Upload successful

documentobject
Show child attributes
- _idstring
- _typestring
  Example: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/image-1234567890-500x400.jpg
- pathstring
- sizenumber
  Size of the asset in bytes.
  Example:202546
- mimeTypestring
  MIME type of the asset.
  Example:image/jpeg
- assetIdstring
- extensionstring
  Example:jpg
- originalFilenamestring
  Example:my-image.jpg
- sha1hashstring
  Example:cd6b7eaf68c33e65ee6866873b9c0e48be84bb01
- metadataobject
  Metadata extracted from the asset. Learn more in the metadata documentation.
  Show child attributes
  _typestring
  Example:sanity.imageMetadata
  dimensionsobject
  Show child attributes
  _typestring
  Example:sanity.imageDimensions
  widthnumber
  Example:500
  heightnumber
  Example:400
  aspectRationumber
  Example:1.25

Upload a file asset

post/files/{dataset}

Upload an file asset to Content Lake. This uploads an file and creates a linked sanity.fileAsset document containing the file metadata.

Path parameters

datasetstringrequired

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 person(s) and/or organization(s) required by the supplier of the asset to be used when published.
sourceNamestring
The name of the source if asset is from an external service.
sourceIdstring
Use with sourceName. The id of the asset within the external source.
sourceUrlstring
Use with sourceName. The url of the asset within the external source.

Request body `image/*`

string (binary)
The file binary to upload.

Responses

Select response

200

Upload successful

documentobject
Show child attributes
- _idstring
- _typestring
  Example:sanity.fileAsset
- _revstring
- _createdAtstring (date-time)
- _updatedAtstring (date-time)
- urlstring (uri)
  Example:https://cdn.sanity.io/files/myproject/mydataset/openAPISpec.yaml
- pathstring
- sizenumber
  Size of the asset in bytes.
  Example:202546
- mimeTypestring
  MIME type of the asset.
  Example:image/jpeg
- assetIdstring
- extensionstring
  Example:jpg
- originalFilenamestring
  Example:my-image.jpg
- sha1hashstring
  Example:cd6b7eaf68c33e65ee6866873b9c0e48be84bb01

Link a Media Library asset to a document

post/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 mutate to attach linked Media Library assets to documents.

Path parameters

datasetstringrequired

Request body `application/json`

assetIdstring
The asset ID of the Media Library asset. This comes from the asset._id field returned as part of the response when uploading an asset to the library.
mediaLibraryIdstring
The id of the Media Library.
assetInstanceIdstring
The asset instance ID of the Media Library asset. This comes from the assetInstance._id field returned as part of the response when uploading an asset to the library.

Responses

Select response

200

Link created successfully

Assets

Authentication

Base API server URL

Variables

Endpoints

Upload an image asset

Path parameters

Query parameters

items

Request body image/*

Responses

Upload a file asset

Path parameters

Query parameters

Request body image/*

Responses

Link a Media Library asset to a document

Path parameters

Request body application/json

Responses

Endpoints

Upload an image asset

Path parameters

Query parameters

items

Request body image/*

Responses

Upload a file asset

Path parameters

Query parameters

Request body image/*

Responses

Link a Media Library asset to a document

Path parameters

Request body application/json

Responses

Request body `image/*`

Request body `image/*`

Request body `application/json`

Request body `image/*`

Request body `image/*`

Request body `application/json`