Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change Site Theme
Sanity logo

Documentation

    • Overview
    • Platform introduction
    • Next.js quickstart
    • Nuxt.js quickstart
    • Astro quickstart
    • React Router quickstart
    • Studio quickstart
    • Build with AI
    • Content Lake
    • Functions
    • APIs and SDKs
    • Visual Editing
    • Blueprints
    • Platform management
    • Dashboard
    • Studio
    • Canvas
    • Media Library
    • App SDK
    • Content Agent
    • HTTP API
    • CLI
    • Libraries
    • Specifications
    • Changelog
    • User guides
    • Developer guides
    • Courses and certifications
    • Join the community
    • Templates

On this page

HTTP API Reference
Overview

  • Content Lake API

    Actions
    Assets
    Copy
    Backups
    Doc
    Export
    History
    Jobs
    Listen
    Live
    Mutation
    Query
    Scheduling
    Webhooks

  • Compute and AI

    Agent Actions
    Embeddings Index

  • Apps

    Media Library

  • Management API

    Access
    Projects
    Roles

On this page

  • Authentication
Endpoints
  • Upload an image asset
  • Upload a file asset
  • Link a Media Library asset to a document
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.

Authentication

  • All requests must be authenticated.

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

Previous

Actions

Next

Copy

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

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

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

200

Link created successfully