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
    • Agent Actions
    • 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
  • Mutate media in the Media Library
  • Query media in the Media Library
  • List references to an asset.
  • Upload an asset to the media library
  • Search for assets and references
  • Create a new signing key
  • List all signing keys
  • Get a specific signing key
  • Delete a signing key
  • Get video playback information
  • Get video playback information headers
  • Redirect to video playback URL
  • Get playback redirect headers
  • Redirect to video rendition URL
  • Get video rendition redirect headers
HTTP API ReferenceLast updated January 28, 2026

Media Library API reference

  • Article
  • Changelog

HTTP endpoints reference for the Media Library API

The Media Library API lets you programmatically interact with assets in your organization’s Media Library.

Want to get started?

Media Library Introduction

Learn about Media Library, how to incorporate it into your workflow, and how to get started.

Upload assets programmatically

Programatically upload assets to your Media Library.

Authentication

  • All requests to private data must be authenticated. Requests to public information, like public assets, are available without an authentication token.
  • Manipulating documents requires read+write access permission for Media Library.

Base API server URL

Media Library API base URL

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

Variables

  • apiVersionstringdefault: "v2025-02-19"

    API version

Media Library API with projectId subdomain base URL

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

Variables

  • projectIdstringdefault: "your-project-id"

    Your Sanity project ID. This can be found in your project settings or in the URL when accessing your project in the Sanity management interface.

  • apiVersionstringdefault: "v2025-02-19"

    API version

Previous

Embeddings Index

Next

Access

Endpoints

Mutate media in the Media Library

post/media-libraries/{libraryId}/mutate

You can use this endpoint to create, update, or delete documents in the Media Library. This uses the same mutation syntax as Content Lake's Mutation API.

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library

Request body application/json

  • mutationsarray
    Show child attributes
    items
    • patch
      Show child attributes
      • idstringrequired
      • ifRevisionIDstring
      • setobjectrequired

Responses

200

Mutation successful

Query media in the Media Library

get/media-libraries/{libraryId}/query

Use GROQ to query the Media Library.

See the GROQ documentation for more information on writing GROQ queries.

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library

Query parameters

  • querystringrequired

Responses

200

OK

  • querystring

    The GROQ query and projection executed against the Media Library.

  • resultstring|number|boolean|array|object|null

    The result of the query. The type of the result depends on the query response.

    For example, if the query returns a single document, the result will be an object. If it returns a list of documents, the result will be an array.

  • syncTagsarray

    A list of sync tags. Sync tags are used with the Live Content API to track document changes.

    Show child attributes
    items
    • string

List references to an asset.

get/media-libraries/{libraryId}/references/documents/{assetId}/to

Get references to an asset document from other documents and datasets. At this time, this does not support draft or version documents.

Note: this endpoint is currently only available on version vX of the API.

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • assetIdstringrequired

    The ID of the asset to get references for.

Query parameters

  • cursorstring

    A cursor to paginate through the results. The cursor is returned in the nextCursor field of the response.

Responses

200

OK

  • referencesarray
    Show child attributes
    items
    • sourceDocumentRefstring

      The global document reference ID of the document that references the asset.

      This is made up of the {resourceName}:{resourceId}.{dataset}:{documentId}.

      Example:dataset:y3d2bw.production:document-id1234
    • sourceFieldPathsarray

      A list of field path locations in the document that reference the asset.

      Example
      ["mainImage.media._ref","body[4].media._ref"]
      Show child attributes
      items
      • string
  • totalCountinteger

    Total number of references found

  • nextCursorstring

    Cursor for paginating to next set of results

Examplesapplication/json
{
  "references": [
    {
      "sourceDocumentRef": "dataset:y856rro4.production:196167ef-8c0b-4d7c-ae18-71179e424c19",
      "sourceFieldPaths": [
        "mainImage.media._ref"
      ]
    },
    {
      "sourceDocumentRef": "dataset:y856rro4.production:503cceed-a1b5-4552-9cc1-c6fddf28de59",
      "sourceFieldPaths": [
        "body[4].media._ref"
      ]
    },
    {
      "sourceDocumentRef": "dataset:y856rro4.production:drafts.196167ef-8c0b-4d7c-ae18-71179e424c19",
      "sourceFieldPaths": [
        "gdrImage._ref",
        "mainImage.media._ref"
      ]
    }
  ],
  "totalCount": 3,
  "nextCursor": "gdr1:eyJucyI6Ink4NTZycm80LnByb2R1Y3Rpb24uS2RSS2c4Z0tJQVFhIiwiaWQiOiJkcmFmdHMuMTk2MTY3ZWYtOGMwYi00ZDdjLWFlMTgtNzExNzllNDI0YzE5In0"
}

Upload an asset to the media library

post/media-libraries/{libraryId}/upload

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library

Query parameters

  • typestringrequired

    Type of asset being uploaded

  • filenamestringrequired

    Original filename

  • titlestring

    Asset title

  • autoGenerateTitleboolean

    Auto-generate title from filename

  • assetIdstring

    Specific asset ID for updates

  • sessionIdstring

    Upload session identifier

  • cdnAccessPolicystring

    CDN access policy

  • sha1string

    SHA1 hash for validation

Request body multipart/form-data

  • filestring (binary)

    The asset file to upload

Responses

200

Asset uploaded successfully

  • assetobjectrequired
    Show child attributes
    • _idstringrequired

      Asset container ID

    • _typestringrequired

      Document type

    • assetTypestringrequired

      Type of asset

    • currentVersionobjectrequired
      Show child attributes
      • _refstringrequired

        Reference ID

      • _typestring

        Reference type

      • _keystring

        Reference key

      • _weakboolean

        Weak reference flag

    • versionsarrayrequired
      Show child attributes
      items
      • _keystringrequired
      • _typestringrequired
      • titlestringrequired
      • instanceobjectrequired
        Show child attributes
        • _refstringrequired

          Reference ID

        • _typestring

          Reference type

        • _keystring

          Reference key

        • _weakboolean

          Weak reference flag

    • cdnAccessPolicystringrequired

      CDN access policy for the asset

    • titlestringrequired
    • aspectsobjectrequired
    • _revstring
    • _createdAtstring (date-time)
    • _updatedAtstring (date-time)
  • assetInstanceobjectrequired

    Asset instance with metadata

  • uploadSessionobjectrequired

    Upload session information

Search for assets and references

get/media-libraries/{libraryId}/refsearch

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library

Query parameters

  • termstringrequired

    Search term

  • filterstring

    Search filter query

  • projectionstring

    Fields to return

  • perspectivestringdefault: "published"

    Data perspective

  • cursorstring

    Pagination cursor

  • limitintegerdefault: 10

    Results limit

Responses

200

Search results

  • object

    Search results from refsearch service

Create a new signing key

post/media-libraries/{libraryId}/signing-keys

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library

Request body application/json

  • namestringrequired

    Name of the signing key

  • keyTypestringdefault: "ed25519"

    Type of signing key

Responses

201

Signing key created successfully

  • idstringrequired

    Signing key ID

  • namestringrequired

    Signing key name

  • publicKeystringrequired

    Public key

  • privateKeystringrequired

    Private key (returned only once)

  • createdAtstring (date-time)required

    Creation timestamp

List all signing keys

get/media-libraries/{libraryId}/signing-keys

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library

Responses

200

List of signing keys

  • keysarrayrequired
    Show child attributes
    items
    • idstringrequired

      Signing key ID

    • namestringrequired

      Signing key name

    • keyTypestringrequired

      Key type

    • publicKeystringrequired

      Public key

    • statusstringrequired

      Status of the signing key

    • createdAtstring (date-time)

      Creation timestamp

    • updatedAtstring (date-time)

      Last update timestamp

    • revokedAtstring (date-time)

      Revocation timestamp

Get a specific signing key

get/media-libraries/{libraryId}/signing-keys/{keyId}

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • keyIdstringrequired

    Signing key identifier

Responses

200

Signing key details

  • idstringrequired

    Signing key ID

  • namestringrequired

    Signing key name

  • keyTypestringrequired

    Key type

  • publicKeystringrequired

    Public key

  • statusstringrequired

    Status of the signing key

  • createdAtstring (date-time)

    Creation timestamp

  • updatedAtstring (date-time)

    Last update timestamp

  • revokedAtstring (date-time)

    Revocation timestamp

Delete a signing key

delete/media-libraries/{libraryId}/signing-keys/{keyId}

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • keyIdstringrequired

    Signing key identifier

Responses

200

Signing key deleted successfully

Get video playback information

get/media-libraries/{libraryId}/video/{videoId}/playback-info

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • videoIdstringrequired

    Video asset instance ID or asset container ID. If a container ID is provided, resolves to the current version.

Query parameters

  • thumbnailWidthinteger

    Thumbnail width

  • thumbnailHeightinteger

    Thumbnail height

  • thumbnailTimenumber

    Thumbnail time position

  • thumbnailFitstring

    Thumbnail fit mode

  • thumbnailFormatstring

    Thumbnail format

  • animatedWidthinteger

    Animated GIF width

  • animatedHeightinteger

    Animated GIF height

  • animatedStartnumber

    Animated GIF start time

  • animatedEndnumber

    Animated GIF end time

  • animatedFpsinteger

    Animated GIF FPS

  • animatedFormatstring

    Animated format

  • storyboardFormatstring

    Storyboard format

  • expirationstring

    URL expiration duration

Responses

200

Video playback information

  • idstringrequired

    Video instance ID

  • thumbnailobject
    Show child attributes
    • urlstring (uri)required

      Playback URL

    • tokenstring

      Access token if required

    • expires_atstring (date-time)

      Expiration timestamp

  • animatedobject
    Show child attributes
    • urlstring (uri)required

      Playback URL

    • tokenstring

      Access token if required

    • expires_atstring (date-time)

      Expiration timestamp

  • storyboardobject
    Show child attributes
    • urlstring (uri)required

      Playback URL

    • tokenstring

      Access token if required

    • expires_atstring (date-time)

      Expiration timestamp

  • streamobject
    Show child attributes
    • urlstring (uri)required

      Playback URL

    • tokenstring

      Access token if required

    • expires_atstring (date-time)

      Expiration timestamp

  • durationnumberrequired

    Video duration in seconds

  • aspectRationumber

    Video aspect ratio

Get video playback information headers

head/media-libraries/{libraryId}/video/{videoId}/playback-info

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • videoIdstringrequired

    Video asset instance ID or asset container ID. If a container ID is provided, resolves to the current version.

Responses

200

Video playback information headers

Redirect to video playback URL

get/media-libraries/{libraryId}/video/{videoId}/playback/{type}

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • videoIdstringrequired

    Video asset instance ID or asset container ID. If a container ID is provided, resolves to the current version.

  • typestringrequired

    Type of playback resource

Responses

302

Redirect to playback URL

Get playback redirect headers

head/media-libraries/{libraryId}/video/{videoId}/playback/{type}

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • videoIdstringrequired

    Video asset instance ID or asset container ID. If a container ID is provided, resolves to the current version.

  • typestringrequired

    Type of playback resource

Responses

302

Redirect headers

Redirect to video rendition URL

get/media-libraries/{libraryId}/video/{videoId}/renditions/{name}

Returns a redirect to the rendition (downloadable MP4) for the specified video

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • videoIdstringrequired

    Video asset instance ID or asset container ID. If a container ID is provided, resolves to the current version.

  • namestringrequired

    Rendition name (e.g., "720p.mp4", "1080p.mp4")

Responses

302

Redirect to rendition URL

Get video rendition redirect headers

head/media-libraries/{libraryId}/video/{videoId}/renditions/{name}

Path parameters

  • libraryIdstringrequired

    Media library identifier

    Example:my-media-library
  • videoIdstringrequired

    Video asset instance ID or asset container ID. If a container ID is provided, resolves to the current version.

  • namestringrequired

    Rendition name (e.g., "720p.mp4", "1080p.mp4")

Responses

302

Redirect headers