canonical: https://jentic.com/apis/sanity.io/sanity-assets

# Sanity Assets

The Sanity Assets API uploads images and files into a dataset in Sanity's Content Lake and creates the matching sanity.imageAsset or sanity.fileAsset document with their metadata. Uploads can come from raw request bytes or from a public HTTPS URL that Sanity fetches itself, with optional title, description, label, credit line, and source attribution. Image uploads can extract metadata such as palette, lqip, blurhash, thumbhash, exif, and location. A separate operation links an existing Media Library asset to a dataset so it can be previewed and referenced from documents.

## For AI agents

Upload images and files to a Sanity dataset from bytes or an HTTPS URL, extract image metadata, and link Media Library assets to the dataset.

## Scope

Does not transform or resize images, delete assets, or edit documents that reference them. Use for uploading images and files to a Sanity dataset and linking Media Library assets only.

## Capabilities

- Upload an image to a dataset and create a sanity.imageAsset document with uploadImageAsset
- Upload any file and create a sanity.fileAsset document whose mimeType comes from the Content-Type header
- Import an image or file from a public HTTPS URL, which Sanity fetches without forwarding your token, up to 50 MiB
- Choose image metadata to extract through the meta parameter, such as palette, lqip, blurhash, exif, or location
- Record attribution with title, creditLine, and the paired sourceName and sourceId parameters
- Link a Media Library asset to a dataset with assetId, mediaLibraryId, and assetInstanceId

## Use cases

### AI agent media upload

An agent that builds pages or posts in Sanity often needs to attach an image it found or generated. Through Jentic the agent searches for 'upload an image to Sanity', loads the uploadImageAssetFromUrl operation, and sends the URL and filename for the dataset while the Sanity token is injected at call time. It then uses the returned document._id as the image reference.

Example prompt: POST `/images/production/from-url` with url https://example.com/hero.jpg and filename hero.jpg, title Spring hero, then return document._id

### Bulk image migration

Moving a media library from another CMS into Sanity means re-uploading many images with their attribution. Each upload accepts title, description, creditLine, and sourceName with sourceId and sourceUrl, and the from-url variant lets Sanity fetch each source over HTTPS, following up to three redirects, so files do not need to be downloaded first.

Example prompt: For each image in a list, POST `/images/staging/from-url` with its url and filename, and set sourceName unsplash, sourceId, and creditLine as query parameters

### Image placeholders and color data

Frontends use low-quality image placeholders and dominant colors to render fast. Uploading with the meta parameter tells Sanity which metadata to extract, defaulting to palette, lqip, blurhash, and thumbhash, with exif and location available for photos where camera and GPS data matter.

Example prompt: POST `/images/production` with the image bytes, filename team.jpg, and meta set to palette, lqip, and exif

### Media Library linking

Assets stored in a Sanity Media Library need a local asset document before a dataset can preview and reference them. The link operation creates that document from an assetId, mediaLibraryId, and assetInstanceId, and requires a Sanity user token because robot tokens are rejected.

Example prompt: POST `/media-library-link/production` with assetId, mediaLibraryId, and assetInstanceId for the chosen asset

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/images/{dataset}` | Upload an image asset |
| POST | `/files/{dataset}` | Upload a file asset |
| POST | `/images/{dataset}/from-url` | Upload an image asset from a URL |
| POST | `/files/{dataset}/from-url` | Upload a file asset from a URL |
| POST | `/media-library-link/{dataset}` | Link a Media Library asset to a dataset |

## Key resources

- **Image assets** — sanity.imageAsset documents holding uploaded images and their extracted metadata
- **File assets** — sanity.fileAsset documents holding uploaded files with mimeType and filename
- **Media Library links** — Local asset documents that connect a Media Library asset to a dataset

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 71 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 72 / 100
  - AI-Readiness & Agent Experience: 51 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 85 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-assets/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Sanity Assets API by hand means templating the projectId and apiVersion into the host, sending raw bytes with the right Content-Type, pairing sourceName with sourceId, and keeping client timeouts past 300 seconds for URL fetches. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Each Assets path carries the dataset name (`/images/{dataset}`, `/files/{dataset}`), so a rule can pin your agent to one dataset and to the upload operations you pick. You choose the operations it may call, so Media Library linking or raw file uploads are not included unless you add them.
- **Credential handling:** Your Sanity token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload an image to Sanity' or 'import a file from a URL into Sanity', and Jentic returns the matching Assets operation with its parameters and body schema.

## Related APIs

- **Sanity HTTP API** — Query and mutate the documents that reference uploaded assets
- **Sanity CDN Cache Purge API** — Purge cached copies of a dataset image or file
- **Cloudinary Upload API** — Upload and transform images and video in Cloudinary
- **Filestack API** — File upload and processing service

## FAQ

### What authentication does the Sanity Assets API use?

Per its OpenAPI spec, the Sanity Assets API uses bearer authentication with a Sanity token in the Authorization header. Linking a Media Library asset needs a token for a Sanity user, since robot tokens are rejected there. Through Jentic the token is stored by your own instance and attached at call time.

### Can I upload an image to Sanity from a URL?

Yes. POST `/images/{dataset}/from-url` takes a JSON body with url and an optional filename. Sanity fetches the source over HTTPS without forwarding your token, follows up to three redirects, and accepts sources up to 50 MiB. Allow more than 300 seconds for the request, and check the dataset before retrying a timed-out upload.

### How does the Sanity Assets API set a file's type?

For direct file uploads, the asset's mimeType comes from the request's Content-Type header, and filename keeps the original extension. For URL uploads, the source's Content-Type is ignored and the type comes from filename or the file content, so pass filename in the JSON body.

### What are the rate limits for the Sanity Assets API?

The OpenAPI spec does not specify request rate limits; it does cap URL sources at 50 MiB and the JSON body at 4 KiB. Check the Sanity documentation at https://www.sanity.io/docs for current API limits for your plan.

### Is there a Sanity Assets MCP server?

You don't need an MCP server to give your agent the Sanity Assets API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent loads the upload operation it needs without carrying extra tool definitions in its context.

### How do I upload an image to Sanity through Jentic?

Search Jentic for 'upload an image to Sanity', load the uploadImageAssetFromUrl operation, and execute POST `/images/{dataset}/from-url` with the url and filename, then use the returned document._id in an image field. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Sanity Assets API?

Yes. A rule that allows only POST `/images/staging/from-url` lets the agent add images to the staging dataset from URLs, while file uploads, Media Library linking, and the production dataset stay outside what it can call. Every call it makes is logged.
