Archive

History

Get document revisions and transactions

The History API lets you request document revisions by a timestamp or a revision ID. 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.

Get a document revision

GET /v2025-02-19/data/history/:dataset/documents/:documentId

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

Gotcha

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.

Query Parameters

  • revision

    string

    Revision ID (_rev) to fetch.

  • time

    datetime

    Time for which the document is fetched.

  • lastRevision

    boolean

    Mutually exclusive with time and revision. Returns the current data for an existing document, or the last state before deletion for a deleted document. Added in v2025-02-19.

As these parameters refer to specific points in the history, only one of them can be specified at a time.

Example

Request with timestamp:

curl -H "Authorization: Bearer <token>" "https://exx11uqh.api.sanity.io/v2021-06-07/data/history/test/documents/b8b866a5-3546-47de-a15d-de149d058b06?time=2019-05-28T17:18:39Z"

This will return a JSON payload:

{
  "documents": [
    {
      "_createdAt": "2019-03-25T15:16:09Z",
      "_id": "b8b866a5-3546-47de-a15d-de149d058b06",
      "_rev": "mXlLqCPElh7uu0wm84cjks",
      "_type": "author",
      "_updatedAt": "2019-05-28T17:16:43Z",
      "name": "dsfasdflol"
    }
  ]
}

Gotcha

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.

Request with revision id:

curl -H "Authorization: Bearer <token>" "https://exx11uqh.api.sanity.io/v2021-06-07/data/history/test/documents/b8b866a5-3546-47de-a15d-de149d058b06?revision=mXlLqCPElh7uu0wm84cjks"

This will return a JSON payload:

{
  "documents": [
    {
      "_createdAt": "2019-03-25T15:16:09Z",
      "_id": "b8b866a5-3546-47de-a15d-de149d058b06",
      "_rev": "mXlLqCPElh7uu0wm84cjks",
      "_type": "author",
      "_updatedAt": "2019-05-28T17:16:43Z",
      "name": "dsfasdflol"
    }
  ]
}

Get transactions for documents

GET /v2021-06-07/data/history/:dataset/transactions/:documentIds

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

URL parameter documentIds are document ids separated by comma.

Query Parameters

  • excludeContent

    boolean

    Exclude the document contents from the responses.

  • fromTime

    datetime

    Time from which the transactions are fetched.

  • toTime

    datetime

    Time until the transactions are fetched.

  • fromTransaction

    string

    Transaction ID (Or, Revision ID) from which the transactions are fetched.

  • toTransaction

    string

    Transaction ID (Or, Revision ID) until the transactions are fetched.

  • authors

    string

    Comma separated list of authors to filter the transactions by.

  • reverse

    boolean

    Return transactions in reverse order.

  • limit

    integer

    Limit the number of returned transactions.

  • effectFormat

    "mendoza"

    "mendoza": Super efficient format for expressing differences between JSON documents. See blog

  • includeIdentifiedDocumentsOnly

    boolean

    Only include the documents that are part of the document ids list

Gotcha

You are required to set excludeContent as true for now.

curl -H "Authorization: Bearer <token>" "https://exx11uqh.api.sanity.io/v2021-06-07/data/history/test/transactions/b8b866a5-3546-47de-a15d-de149d058b06?excludeContent=true"

This outputs a NDJSON payload:

{"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"]}

Was this page helpful?