HTTP API ReferenceLast updated January 28, 2026

Media Library API reference

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

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
  Select any
  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

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

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

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

Select response

302

Redirect headers

Media Library Introduction

Upload assets programmatically

Authentication

Base API server URL

Variables

Variables

Endpoints

Mutate media in the Media Library

Path parameters

Request body application/json

items

Responses

Query media in the Media Library

Path parameters

Query parameters

Responses

items

List references to an asset.

Path parameters

Query parameters

Responses

items

items

Upload an asset to the media library

Path parameters

Query parameters

Request body multipart/form-data

Responses

items

Search for assets and references

Path parameters

Query parameters

Responses

Create a new signing key

Path parameters

Request body application/json

Responses

List all signing keys

Path parameters

Responses

items

Get a specific signing key

Path parameters

Responses

Delete a signing key

Path parameters

Responses

Get video playback information

Path parameters

Query parameters

Responses

Get video playback information headers

Path parameters

Responses

Redirect to video playback URL

Path parameters

Responses

Get playback redirect headers

Path parameters

Responses

Redirect to video rendition URL

Path parameters

Responses

Get video rendition redirect headers

Path parameters

Responses

Request body `application/json`

Request body `multipart/form-data`

Request body `application/json`