API CDN

Description of the CDN-distributed, cached version of the Sanity API.

Sanity provides two APIs:

  1. api.sanity.io: the live, uncached API. This is the default and will always give you the freshest data, but requests will be slower because they need to reach our backend on every request. Requests are also more costly because they will trigger more computation on our servers.
  2. apicdn.sanity.io: the CDN-distributed, cached API, which is an opt-in feature that will give you very fast responses to requests that have been cached. We encourage most users to use this API for their front-ends unless there is a good reason not to.

To use the API CDN, simply use apicdn.sanity.io instead of api.sanity.io. Most clients provide a useCdn option that makes this switch seamless.

Cache Policy

The API CDN is primarily meant to cache public query results, and as such the following requests are not cached:

  • Non-GET/HEAD/OPTIONS requests are rejected, including mutations (document writes)
    (For GraphQL we also cache POST requests, as they are always read only).
  • Listeners are redirected to the live API (subscriptions to real-time updates)
  • Cookies are removed from requests, including authentication cookies
  • Requests with Authorization headers are rejected, i.e. authenticated requests
  • Responses larger than 10 MB are not cached
  • Non-200 responses are not cached

All official clients will automatically fall back to using the live API where appropriate.

Invalidation

The entire cache for a dataset is invalidated whenever there is a write to a non-draft document in the dataset. Invalidations may take up to 60 seconds to fully propagate.

In some edge cases for rarely used queries, you can experience a delay of up to 10 minutes.

If the backend serves an error, we will serve stale content if the content is less than 2 hours old.

Locations

Sanity currently has CDN nodes in these locations:

  • Asia: Hong Kong
  • Australia: Sydney
  • Europe: Belgium
  • South America: Sao Paolo, Brazil
  • United States: Oregon, Iowa, and Northern Virginia

Was this article helpful?