Content Lake (Datastore)Last updated June 19, 2025

Upload, query, and delete assets

Programmatically manage assets in your project dataset.

In cases where the UI doesn't offer enough control or automation, you can use Sanity's APIs to interact with assets.

The techniques in this guide apply to assets stored in a project's dataset. Reference the Managing assets portion of the Media Library documentation for details on working with Media Library assets.

For details on rendering and transforming assets for your front end applications, see the Presenting Images documentation.

Upload an asset

In cases where uploading assets in the UI is impractical, like batch uploads or migrations, you can use the API directly.

import {createClient} from '@sanity/client'
import {basename} from 'path'
import {createReadStream} from 'fs'

const client = createClient({
  projectId: 'myProjectId',
  dataset: 'myDatasetName',
  apiVersion: '2021-08-29',
  token: 'myToken'
})

const filePath = '/Users/mike/images/bicycle.jpg'

client.assets
  .upload('image', createReadStream(filePath), {
    filename: basename(filePath)
  })
  .then(imageAsset => {
    // Here you can decide what to do with the returned asset document. 
    // If you want to set a specific asset field you can with the following:
    return client
      .patch('some-document-id')
      .set({
        theImageField: {
          _type: 'image',
          asset: {
            _type: "reference",
            _ref: imageAsset._id
          }
        }
      })
      .commit()
  })
  .then(() => {
    console.log("Done!");
  })

import {useClient} from 'sanity'
import {basename} from 'path'
import {createReadStream} from 'fs'

// ... omitted for brevity
// inside a React component
const client = useClient({apiVersion: '2025-02-19'})

const file = new File(['foo'], 'foo.txt', {type: 'text/plain'})
// Upload it
client.assets
  .upload('file', file)
  .then((document) => {
    console.log('The file was uploaded!', document)
  })
  .catch((error) => {
    console.error('Upload failed:', error.message)
  })

curl \
  -X POST \
  -H 'Content-Type: image/jpeg' \
  --data-binary "@/Users/mike/images/bicycle.jpg" \
  'https://myProjectId.api.sanity.io/v2021-06-07/assets/images/myDataset'

{
  "_id": "image-abc123_0G0Pkg3JLakKCLrF1podAdE9-538x538-jpg",
  "_type": "sanity.imageAsset", // type is prefixed by sanity schema
  "assetId": "0G0Pkg3JLakKCLrF1podAdE9",
  "path": "images/myproject/mydataset/abc123_0G0Pkg3JLakKCLrF1podAdE9-538x538.jpg",
  "url": "https://cdn.sanity.io/images/myproject/mydataset/abc123_0G0Pkg3JLakKCLrF1podAdE9-538x538.jpg",
  "originalFilename": "bicycle.jpg",
  "size": 2097152, // File size, in bytes
  "metadata": {
    "dimensions": {
      "height": 538,
      "width": 538,
      "aspectRatio": 1.0
    },
    "location":{ // only present if the original image contained location metadata
      "lat": 59.9241370,
      "lon": 10.7583846,
      "alt": 21.0
    }
  }
}

Resources

Assets API

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

@sanity/client

Documentation for the @sanity/client library

Query and browse assets

To browse project assets from the Studio interface, install the Sanity Media plugin. This adds a new tool to the toolbar and enables Studio users to browse and manage assets.

You can also query all images with GROQ using the following query:

Run GROQ queries through Vision, the client, or with the Query API.

You can also use this method to query Media Library assets that have been linked to your dataset.

If viewing asset data within another document type, you'll need to follow the asset's reference to view the metadata or URL. For example:

Deleting assets

Deleting an asset can be performed by deleting the associated asset document.

import {createClient} from '@sanity/client'
const config = {
  projectId: 'myProjectID',
  dataset: 'mydataset',
  apiVersion: '2021-08-29',
  token: 'myToken'
}
const client = createClient(config)
// Note: this is the _id of the asset document.
client.delete('image-abc123_0G0Pkg3JLakKCLrF1podAdE9-538x538-jpg')
  .then(result => {
    console.log('deleted image asset', result)
  })

It's important to note that while the file is deleted, the CDN might have your asset cached so it may not disappear immediately.

Download assets

In order to download an asset you need to append ?dl=<asset-of-your-choice.jpg> to the asset URL. If you leave the filename blank, the original filename will be used if present. If the original filename is not available, the id of the file will be used instead.

Introduction

Transactions

Was this page helpful?