Index
Edit

History

The History API lets you request document revisions by a timestamp or a revision ID. All requests have to be authenticated.

GET /history/:dataset/document/(:time|:revision)

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.

Parameters

  • revision (string): revision ID (_rev) to fetch.
  • time (datetime): time for which the document is fetched.

Since these parameters are conflicting with each other, if both specified in a request, request fails hard.

Example

Request with timestamp:

curl -H "Authorization: Bearer <token>" "https://exx11uqh.api.sanity.io/v1/data/history/test/document/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/v1/data/history/test/document/b8b866a5-3546-47de-a15d-de149d058b06?_rev=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 /history/:dataset/transactions/:document_ids

Returns an NDJSON (Newline Delimited JSON) with the transactions for the documents specified by a comma separated list of document_ids.

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 (int): Limit the number of returned transactions.
Gotcha

You are required to set excludeContent as true for now.

curl -H "Authorization: Bearer <token>" "https://exx11uqh.api.sanity.io/v1/data/history/test/transactions/b8b866a5-3546-47de-a15d-de149d058b06?exludeContent=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"]}

Previous: ExportNext: Command Line Interface