HTTP API Reference

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.

Authentication

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

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

200

Upload successful

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

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

200

Upload successful

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

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

200

Link created successfully