canonical: https://jentic.com/apis/sanity.io/sanity-cdn-cache-purge

# Sanity CDN Cache Purge API

The Sanity CDN Cache Purge API clears cached content from Sanity's CDN for one dataset at a time. One operation purges the cached GROQ and GraphQL query results for a dataset, and the other purges every cached representation of a single image or file, identified by its asset ID such as image-<sha1>-<width>x<height>-<format>. Both accept an empty POST body and return 202 with a purgeId and acceptedAt time while the purge runs in the background. Self-service cache purging must be enabled for the project, and the token needs permission to update project datasets.

## For AI agents

Purge Sanity CDN caches for one dataset's GROQ and GraphQL query results, or for every cached version of one image or file asset.

## Scope

Does not upload assets, edit documents, or configure custom domains. Use for purging Sanity CDN caches of dataset query results and individual assets only.

## Capabilities

- Purge cached GROQ and GraphQL query results for one dataset with purgeDataset
- Purge every cached representation of a single dataset image or file with purgeDatasetAsset
- Target an asset by its document _id or reference _ref, in image-<sha1>-<width>x<height>-<format> or file-<sha1>-<extension> form
- Track an accepted purge by the returned purgeId and acceptedAt timestamp
- Back off on 429 responses using the Retry-After and RateLimit-Remaining headers

## Use cases

### AI agent cache refresh after edits

After an agent corrects published content, readers may still see the cached version. Through Jentic the agent searches for 'purge Sanity CDN cache', loads the purgeDataset operation, and posts an empty body for the project and dataset while the Sanity token is injected at call time. It records the returned purgeId in case support needs it.

Example prompt: POST `/v1/projects/abcd1234/datasets/production/purges` with an empty body and report the purgeId and acceptedAt from the 202 response

### Replacing a published image or file

When a logo, product shot, or document is replaced, old copies can keep serving from the CDN. The asset purge operation takes the asset's _id or _ref, such as image-<sha1>-2000x1500-jpg, and purges all of its cached representations in one request.

Example prompt: POST `/v1/projects/abcd1234/datasets/production/assets/image-0123456789abcdef0123456789abcdef01234567-2000x1500-jpg/purges` with an empty body

### Purge as a publish pipeline step

Deployment scripts can purge the query cache right after a content import so the site picks up the change. The API answers 202 once a purge is durably accepted, returns 403 with feature_not_included_in_plan when the project lacks self-service purging, and 429 with Retry-After when the project's request limit is reached.

Example prompt: After an import to the staging dataset, POST `/v1/projects/abcd1234/datasets/staging/purges` and retry after the Retry-After seconds if the response is 429

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/projects/{project_id}/datasets/{dataset_name}/purges` | Purge cached query responses for one dataset |
| POST | `/v1/projects/{project_id}/datasets/{dataset_name}/assets/{asset_id}/purges` | Purge one dataset image or file |

## Key resources

- **Dataset query cache** — Cached GROQ and GraphQL query results for one dataset
- **Asset cache** — All cached representations of one image or file asset
- **Purges** — Accepted purge requests identified by purgeId and acceptedAt

## 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:** 72 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 100 / 100
  - Developer Experience & Jentic Compatibility: 78 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/sanity.io/sanity-cdn-cache-purge/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 CDN Cache Purge API by hand means sending a user or robot bearer token with dataset update permission, building asset IDs in the exact image-<sha1>-<width>x<height>-<format> shape, and honouring Retry-After on 429s. Through Jentic you install once, import it from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Both purge paths carry the project and dataset (`/v1/projects/{project_id}/datasets/{dataset_name}/...`), so a rule can pin your agent to one dataset, and to single-asset purges only if you prefer. You choose the operations it may call, so the whole-dataset query purge is not included unless you add it.
- **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 'purge Sanity CDN cache' or 'clear a cached Sanity image', and Jentic returns the matching purge operation with its path parameters.

## Related APIs

- **Sanity Assets API** — Upload images and files to a Sanity dataset
- **Sanity Actions API** — Publish and unpublish Sanity documents
- **Cloudflare API** — CDN, DNS, and cache purge for your own zones
- **bunny.net API** — CDN pull zones and cache purging

## FAQ

### What authentication does the Sanity CDN Cache Purge API use?

Per its OpenAPI spec, the Sanity CDN Cache Purge API uses a bearer token: a user or robot token with permission to update project datasets, which the Administrator and Developer roles include. A missing or expired token returns 401 with unauthenticated. Through Jentic the token is stored by your own instance and attached at call time.

### Does a Sanity cache purge happen immediately?

The API returns 202 once the purge is durably accepted, and the purge itself runs in the background. The response's acceptedAt time marks the start of Sanity's two-hour completion commitment. See https://www.sanity.io/docs/content-lake/purge-cdn-caches for completion guarantees.

### Why does my Sanity purge request return 403?

The spec lists three 403 codes: invalid_principal_type when the token is not a user or robot token, insufficient_permissions when it cannot purge that dataset, and feature_not_included_in_plan when self-service cache purging is not available for the project.

### What are the rate limits for the Sanity CDN Cache Purge API?

The OpenAPI spec does not state a numeric limit. It returns 429 when the project's request limit is reached, with RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After headers. See https://www.sanity.io/docs/content-lake/purge-cdn-caches for the current limits.

### Is there a Sanity CDN Cache Purge MCP server?

You don't need an MCP server to give your agent the Sanity CDN Cache Purge API. Jentic connects it directly from the API Directory: import it, store your Sanity token once, and your agent calls the purge operation it needs.

### How do I purge the Sanity CDN cache through Jentic?

Search Jentic for 'purge Sanity CDN cache', load the purgeDataset operation, and execute POST `/v1/projects/{project_id}/datasets/{dataset_name}/purges` with an empty body. 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 CDN Cache Purge API?

Yes. Write a rule that allows only the asset purge under `/v1/projects/abcd1234/datasets/staging/assets`, and the agent can clear individual images and files in staging while whole-dataset purges and the production dataset stay outside its reach. Every call it makes is logged.
