> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge document history

> Read saved document versions and compare changes over time.

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

## List versions

```http theme={null}
GET /api/knowledge/{id}/history?limit=20&offset=0
x-token: YOUR_API_KEY
```

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

```http theme={null}
GET /api/knowledge/{id}/history/{versionId}?offset=0
x-token: YOUR_API_KEY
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.