Sanity logosanity.ioAll Systems Operational© Sanity 2026
Change Site Theme
Sanity logo

Documentation

    • Overview
    • Platform introduction
    • Next.js quickstart
    • Nuxt.js quickstart
    • Astro quickstart
    • React Router quickstart
    • Studio quickstart
    • Build with AI
    • Content Lake
    • Functions
    • APIs and SDKs
    • Agent Actions
    • Visual Editing
    • Blueprints
    • Platform management
    • Dashboard
    • Studio
    • Canvas
    • Media Library
    • App SDK
    • Content Agent
    • HTTP API
    • CLI
    • Libraries
    • Specifications
    • Changelog
    • User guides
    • Developer guides
    • Courses and certifications
    • Join the community
    • Templates

On this page

HTTP API Reference
Overview

  • Content Lake API

    Actions
    Assets
    Copy
    Backups
    Doc
    Export
    History
    Jobs
    Listen
    Live
    Mutation
    Query
    Scheduling
    Webhooks

  • Compute and AI

    Agent Actions
    Embeddings Index

  • Apps

    Media Library

  • Management API

    Access
    Projects
    Roles

On this page

  • Authentication
Endpoints
  • Get a document revision
  • Get all transactions
  • Get the transactions for a list of documents
HTTP API ReferenceLast updated January 9, 2026

History API reference

Reference documentation for the History HTTP endpoint.

The History API lets you request document revisions by a timestamp or a revision ID.

Authentication

  • All requests must be authenticated.
  • To read transactions for a document, you must have read access to the document's current version.
  • If your document is in a private dataset you must be authenticated.

Base API server URL

Sanity API base URL

https://{projectId}.api.sanity.io/{apiVersion}

Variables

  • projectIdstringdefault: "projectId"

    Project ID

  • apiVersionstringdefault: "v2025-02-19"

    API version

Previous

Export

Next

Jobs

Endpoints

Get a document revision

get/data/history/{dataset}/documents/{documentId}

Returns a document as it was at a point in the past. This endpoint behaves the same as the /doc endpoint. It applies the current access control to every revision of the document.

Note: Current Access Control means if you're able to access the document today, you'll be able to access all the previous revisions of the document.

Path parameters

  • datasetstringrequired
  • documentIdstringrequired

Query parameters

  • revisionstring

    The revision ID (_rev) to fetch. Mutually exclusive with time and lastRevision.

  • timestring (date-time)

    Time to fetch the document at. Mutually exclusive with lastRevision and revision.

  • lastRevisionboolean

    If true, only the last revision will be returned, or the last state before deletion for a deleted document. Mutually exclusive with time and revision.

Responses

200

Returns the document revision.

Note: The timestamp is matched against the time of the transaction in the backend, and not the timestamps in the document. In most cases these will align, but if you have imported documents with the timestamps already set, there will be a discrepancy.

  • documentsarray
    Show child attributes
    items
    • _idstring

      The document ID

      Example:123456
    • _createdAtstring (date-time)

      The date and time the document was created.

      Example:2021-01-01T00:00:00Z
    • _updatedAtstring (date-time)

      The date and time the document was last updated.

      Example:2021-01-01T00:00:00Z
    • _revstring

      The revision ID (_rev) of the document.

      Example:123456
    • _typestring

      The type of the document.

      Example:article
    • additionalProperties

Get all transactions

get/data/history/{dataset}/transactions

Returns an NDJSON (Newline Delimited JSON) containing transactions for all documents. Using with limit is highly recommended.

Path parameters

  • datasetstringrequired

Query parameters

  • excludeContentbooleandefault: false

    Exclude the document contents from the response.

  • fromTimestring (date-time)

    Only include transactions from this timestamp onwards.

  • toTimestring (date-time)

    Only include transactions up to this timestamp.

  • fromTransactionstring

    Only include transactions from this Transaction ID (or Revision ID) onwards.

  • toTransactionstring

    Only include transactions up to this Transaction ID (or Revision ID).

  • authorsstring

    Only include transactions by these authors.

  • reversebooleandefault: false

    Return the transactions in reverse order.

  • limitinteger

    Limit the number of transactions returned.

  • effectFormatstringdefault: "mendoza"

    The format of the effect. Uses mendoza, a super efficient format for expressing differences between JSON documents.

  • includeIdentifiedDocumentsOnlybooleandefault: false

    Only include the documents that are part of the document IDs list.

Responses

200

OK

  • string (binary)

    An NDJSON payload containing the transactions for the given document IDs.

    Example:{"id":"mXlLqCPElh7uu0wm84cjks","timestamp":"2019-05-28T17:16:43.151928Z","author":"pDYrmFKn7","mutations":[{"create":{"_id":"b8b866a5-3546-47de-a15d-de149d058b06","_rev":"mXlLqCPElh7uu0wm84cjks"}},{"delete":{"id":"drafts.b8b866a5-3546-47de-a15d-de149d058b06","purge":false}}],"documentIDs":["b8b866a5-3546-47de-a15d-de149d058b06","drafts.b8b866a5-3546-47de-a15d-de149d058b06"]} {"id":"mXlLqCPElh7uu0wm84ckxR","timestamp":"2019-05-28T17:18:39.223739Z","author":"pDYrmFKn7","mutations":[{"patch":{"id":"b8b866a5-3546-47de-a15d-de149d058b06","ifRevisionID":"mXlLqCPElh7uu0wm84cjks"}},{"createOrReplace":{"_id":"b8b866a5-3546-47de-a15d-de149d058b06","_rev":"mXlLqCPElh7uu0wm84cjks"}},{"delete":{"id":"drafts.b8b866a5-3546-47de-a15d-de149d058b06","purge":false}}],"documentIDs":["b8b866a5-3546-47de-a15d-de149d058b06","drafts.b8b866a5-3546-47de-a15d-de149d058b06"]} {"id":"3wHuOovAQT3V1vksbN2QtG","timestamp":"2019-06-11T13:06:02.028674Z","author":"psb9Tdtwv","mutations":[{"delete":{"id":"b8b866a5-3546-47de-a15d-de149d058b06","purge":false}},{"delete":{"id":"drafts.b8b866a5-3546-47de-a15d-de149d058b06","purge":false}}],"documentIDs":["b8b866a5-3546-47de-a15d-de149d058b06"]}

Get the transactions for a list of documents

get/data/history/{dataset}/transactions/{documentIds}

Returns an NDJSON (Newline Delimited JSON) containing transactions for the given document ids.

Path parameters

  • datasetstringrequired
  • documentIdsstringrequired

Query parameters

  • excludeContentbooleandefault: false

    Exclude the document contents from the response.

  • fromTimestring (date-time)

    Only include transactions from this timestamp onwards.

  • toTimestring (date-time)

    Only include transactions up to this timestamp.

  • fromTransactionstring

    Only include transactions from this Transaction ID (or Revision ID) onwards.

  • toTransactionstring

    Only include transactions up to this Transaction ID (or Revision ID).

  • authorsstring

    Only include transactions by these authors.

  • reversebooleandefault: false

    Return the transactions in reverse order.

  • limitinteger

    Limit the number of transactions returned.

  • effectFormatstringdefault: "mendoza"

    The format of the effect. Uses mendoza, a super efficient format for expressing differences between JSON documents.

  • includeIdentifiedDocumentsOnlybooleandefault: false

    Only include the documents that are part of the document IDs list.

Responses

200

OK

  • string (binary)

    An NDJSON payload containing the transactions for the given document IDs.

    Example:{"id":"mXlLqCPElh7uu0wm84cjks","timestamp":"2019-05-28T17:16:43.151928Z","author":"pDYrmFKn7","mutations":[{"create":{"_id":"b8b866a5-3546-47de-a15d-de149d058b06","_rev":"mXlLqCPElh7uu0wm84cjks"}},{"delete":{"id":"drafts.b8b866a5-3546-47de-a15d-de149d058b06","purge":false}}],"documentIDs":["b8b866a5-3546-47de-a15d-de149d058b06","drafts.b8b866a5-3546-47de-a15d-de149d058b06"]} {"id":"mXlLqCPElh7uu0wm84ckxR","timestamp":"2019-05-28T17:18:39.223739Z","author":"pDYrmFKn7","mutations":[{"patch":{"id":"b8b866a5-3546-47de-a15d-de149d058b06","ifRevisionID":"mXlLqCPElh7uu0wm84cjks"}},{"createOrReplace":{"_id":"b8b866a5-3546-47de-a15d-de149d058b06","_rev":"mXlLqCPElh7uu0wm84cjks"}},{"delete":{"id":"drafts.b8b866a5-3546-47de-a15d-de149d058b06","purge":false}}],"documentIDs":["b8b866a5-3546-47de-a15d-de149d058b06","drafts.b8b866a5-3546-47de-a15d-de149d058b06"]} {"id":"3wHuOovAQT3V1vksbN2QtG","timestamp":"2019-06-11T13:06:02.028674Z","author":"psb9Tdtwv","mutations":[{"delete":{"id":"b8b866a5-3546-47de-a15d-de149d058b06","purge":false}},{"delete":{"id":"drafts.b8b866a5-3546-47de-a15d-de149d058b06","purge":false}}],"documentIDs":["b8b866a5-3546-47de-a15d-de149d058b06"]}