Skip to main content
List saved versions of a knowledge document, then read the versions you want to compare. These endpoints are read-only.

​
List versions

The response contains documentId, the current name, current update metadata, versions, nextOffset, and a note about history coverage. Each version includes:
  • versionId and the historical name.
  • savedAt, savedBy, and savedByName.
  • conduit: hiro means saved through Hiro.
  • Emoji, icon, and cover metadata, when available.
Versions are newest first. Pass nextOffset as offset until it is null. limit defaults to 20 and can be 1–50. Optional filters are savedBy (user ID), savedFrom, and savedTo. Date bounds are inclusive. Use timestamps with a timezone to select local calendar days; date-only values mean midnight UTC, with no end-of-day expansion.

​
Read a version

The response contains snapshot metadata and read-only blocks, plus total and nextOffset. The top-level name is the current title; snapshot.name is the title at the saved version. Blocks contain IDs, types, text, and truncation flags. Pages contain up to 20 top-level blocks and 20,000 text characters. Individual blocks are capped at 10,000 characters and report truncated: true when longer. Offsets count blocks. Specialized blocks may omit non-text or formatting details; unsupported legacy formats return 400. The endpoint does not expose an editing token or restore the version.

​
Compare changes and identify savers

Read adjacent versions to identify what changed between their save times. To compare changes within a date range, also fetch the preceding version as a baseline; a date-filtered list may exclude it. Fetch the current document through GET /api/knowledge/{id} when you need its latest state. savedBy identifies the recorded saver, not necessarily the author of every passage. Rapid saves may merge, older versions may be pruned (normally 50 versions are retained), and some write paths do not create history. Hiro saves before and after snapshots under the same approver. Use these records as saved-version evidence, not a complete audit of every edit. Unsaved drafts are not included.

​
Access

Use the existing Knowledge API authentication: API key, delegate token with knowledge read access, or partner token with knowledge-docs. Partner callers also pass companyId as a query parameter. Delegate callers must remain active company members and currently be able to view the document. Removed or archived memberships return 403 even before the delegate token expires. Membership and document/team permissions are checked against primary storage on every page. API keys and partner tokens are company-scoped. Archived documents are always excluded. Missing, archived, or inaccessible documents return 404, as does a version that does not belong to the named document and company. Access is rechecked on every page. Snapshots older than the current document’s creation time are excluded, so reusing a deleted document ID does not expose its previous history. Legacy documents without a creation timestamp retain permission-based filtering. Invalid filters, pagination, or attempts to include archived documents return 400.