Using Sanity History API for Page Version Navigation

Great question! Building a historical version navigator is definitely doable with Sanity's History API. Here's what you need to know based on my experience and the docs:

Using the History API

You're correct that the History API isn't directly exposed through @sanity/client. Instead, you'll need to make direct HTTP requests to the history endpoints. The main endpoint you'll want to use is:

https://${projectId}.apicdn.sanity.io/v1/data/history/${dataset}/documents/${docId}?time=${time}

This lets you fetch a document as it existed at a specific point in time, which is perfect for your dropdown navigation use case.

Implementation Approach

Here's a practical approach for building your version dropdown:

1. Fetch transaction history to get a list of all revisions:

const historyUrl = `https://${projectId}.apicdn.sanity.io/v1/data/history/${dataset}/transactions/${docId}`;
const response = await fetch(historyUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

2. Parse the transactions to build your dropdown menu - each transaction gives you a timestamp and change information

3. Fetch specific versions when users select from the dropdown using the time parameter shown above

Important Considerations

History retention limits - Make sure you're aware of what your plan offers:

• Free: 3 days
• Growth: 90 days
• Enterprise: 365 days or custom

Input sanitization - Since you're building user-facing features, be sure to properly validate and sanitize document IDs and timestamps to prevent security issues. The History API documentation specifically calls this out.

Using client.request() - While the History API isn't built into the standard client methods, you can use the lower-level client.request() method to make authenticated requests to the history endpoints without manually handling tokens:

const history = await client.request({
  url: `/data/history/${dataset}/documents/${docId}?time=${timestamp}`,
  withCredentials: true
});

This approach keeps your authentication handled by the client while still accessing the history endpoints.

Alternative: Document Revisions

If you need simpler access to recent changes, the document history feature in the Studio UI shows revisions, and you can programmatically restore documents using client.createOrUpdate() with data from historical versions.

Hope this helps! Let me know how it goes with your implementation.