Index
Edit

Assets

Files, like JPGs and PDFs, which exist alongside your data, are considered assets. Sanity provides a hassle-free UI for managing assets, and an unsurprising API for dealing with all asset concerns such as storage, resizing and deletion.

Just here for the code? Scroll down to Upload an Asset.

Asset types

image and file. In the future, we might provide specific support for audio and video files, but currently all non-image files belong in the file category.

Images

Our currently supported image formats are: JPEG, PNG and WebP.

To upload assets, use the /assets/images/<dataset> endpoint. Once you have the image URL you can request resized versions of the original image by appending query parameters. See the Presenting Images documentation for more details.

Files

When you need to upload a non-image file (say a PDF or a zip file) use the /assets/files/<dataset> endpoint. The response is similar to the one you get from an image, but the type will be fileAsset.

Upload an Asset

In some cases, uploading assets using the UI is impractical. Say you want to upload a ton of images. If so, you'll want to use the assets API directly.

To upload an image, do a POST request to

myProject.api.sanity.io/v1/assets/images/myDataset

with your file in the request body. E.g.:

curl \
  -X POST \
  -H 'Content-Type: image/jpeg' \
  --data-binary "@/Users/mike/images/bicycle.jpg" \
  'https://myProject.api.sanity.io/v1/images/myDataset'
import sanityClient from '@sanity/client'
import {createReadStream} from 'fs'
const config = {
  project: 'myProject',
  dataset: 'myDataset',
  token: 'myToken'
}
const client = sanityClient(config)
const filePath = '/Users/mike/images/bicycle.jpg'
client.assets.upload('image', createReadStream(filePath))
  .then(imageAsset => {
    console.log('got imageAsset', imageAsset)
  })
{
  "_id": "image-abc123_0G0Pkg3JLakKCLrF1podAdE9-538x538-jpg",
  "_type": "sanity.imageAsset", // type is prefixed by sanity schema
  "assetId": "0G0Pkg3JLakKCLrF1podAdE9",
  "project": "myproject",
  "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
    }
  }
}

Deleting Assets

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

import sanityClient from '@sanity/client'
const config = {
  project: 'myproject',
  dataset: 'mydataset',
  token: 'myToken'
}
const client = sanityClient(config)
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 distributed CDN might have the asset cached and will not necessarily disappear immediately.

Previous: Using JSONMatchNext: Webhooks