HTTP API Reference

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

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

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

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

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