# Notes: Document Versions

**Page:** api/notes/versions

[Download Raw Markdown](./api/notes/versions.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Notes Document Versions API lets you capture, retrieve, restore, and delete version snapshots for documents within a notebook. Use these endpoints to implement version history, audit trails, undo flows, or branching workflows for collaborative notes.

## List document versions

### `GET /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions`

Lists all versions for a document, ordered by revision descending.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `notebookId` | path | string | Yes | ID of the notebook that contains the document |
| `nodeId` | path | string | Yes | ID of the document node |
| `limit` | query | integer | No | Maximum number of versions to return. Default: `20` |
| `offset` | query | integer | No | Number of versions to skip for pagination. Default: `0` |

### Response



```json
{
  "versions": [
    {
      "id": "vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA",
      "documentId": "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
      "revision": 12,
      "createdAt": "2026-01-15T14:22:09.512Z",
      "createdBy": "usr_01HXVZ0Y1X2W3V4U5T6S7R8Q9P"
    },
    {
      "id": "vrs_01HXY7J8B1N2M3L4K5J6I7H8GWA",
      "documentId": "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
      "revision": 11,
      "createdAt": "2026-01-14T09:45:31.000Z",
      "createdBy": "usr_01HXVZ0Y1X2W3V4U5T6S7R8Q9P"
    }
  ],
  "total": 12
}
```


```json
{
  "message": "You do not have permission to view versions of this document",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "nodeId",
      "message": "Caller is not a collaborator on the parent notebook"
    }
  ]
}
```


```json
{
  "message": "Document not found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "nodeId",
      "message": "No document exists with the given ID in this notebook"
    }
  ]
}
```



### SDK usage

```ts
const { versions, total } = await client.notes.versions.list({
  notebookId: "ntb_01HXY1Z2A3B4C5D6E7F8G9H0J",
  nodeId: "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
  limit: 50,
  offset: 0,
});
```

```bash
curl -X GET "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXY1Z2A3B4C5D6E7F8G9H0J/nodes/nd_01HXY2A3B4C5D6E7F8G9H0J1KA/versions?limit=20&offset=0" \
  -H "Authorization: Bearer <token>"
```

## Get a specific document version

### `GET /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions/{versionId}`

Retrieves a specific document version by ID, including the full stored content.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `notebookId` | path | string | Yes | ID of the notebook that contains the document |
| `nodeId` | path | string | Yes | ID of the document node |
| `versionId` | path | string | Yes | ID of the version to retrieve |

### Response



```json
{
  "id": "vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA",
  "documentId": "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
  "revision": 12,
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "text": "Updated onboarding checklist for Q1."
      }
    ]
  },
  "createdAt": "2026-01-15T14:22:09.512Z",
  "createdBy": "usr_01HXVZ0Y1X2W3V4U5T6S7R8Q9P"
}
```


```json
{
  "message": "You do not have permission to view this document version",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "versionId",
      "message": "Caller lacks read access on the parent document"
    }
  ]
}
```


```json
{
  "message": "Document version not found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "versionId",
      "message": "No version exists with the given ID for this document"
    }
  ]
}
```



### SDK usage

```ts
const version = await client.notes.versions.get({
  notebookId: "ntb_01HXY1Z2A3B4C5D6E7F8G9H0J",
  nodeId: "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
  versionId: "vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA",
});
```

```bash
curl -X GET "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXY1Z2A3B4C5D6E7F8G9H0J/nodes/nd_01HXY2A3B4C5D6E7F8G9H0J1KA/versions/vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA" \
  -H "Authorization: Bearer <token>"
```

## Create a document version snapshot

### `POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions`

Captures the current document content as a new version snapshot. Each call increments the document's revision counter.


The new version stores the document's content at the time of the call. Subsequent edits to the document do not modify historical versions.


### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `notebookId` | path | string | Yes | ID of the notebook that contains the document |
| `nodeId` | path | string | Yes | ID of the document node to snapshot |

### Response



```json
{
  "id": "vrs_01HXY9L0D3Q4R5S6T7U8V9W0XBY",
  "documentId": "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
  "revision": 13,
  "createdAt": "2026-01-16T11:08:42.219Z",
  "createdBy": "usr_01HXVZ0Y1X2W3V4U5T6S7R8Q9P"
}
```


```json
{
  "message": "You do not have permission to snapshot this document",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "nodeId",
      "message": "Caller does not have write access on the document"
    }
  ]
}
```


```json
{
  "message": "Document not found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "nodeId",
      "message": "No document exists with the given ID in this notebook"
    }
  ]
}
```



### SDK usage

```ts
const snapshot = await client.notes.versions.create({
  notebookId: "ntb_01HXY1Z2A3B4C5D6E7F8G9H0J",
  nodeId: "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
});
```

```bash
curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXY1Z2A3B4C5D6E7F8G9H0J/nodes/nd_01HXY2A3B4C5D6E7F8G9H0J1KA/versions" \
  -H "Authorization: Bearer <token>"
```

## Restore a document version

### `POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions/{versionId}/restore`

Restores a document to a previous version by updating its content to match the snapshot. The restore itself produces a new revision so the prior state is preserved in history.


Restoring overwrites the current document content. The live content is not recoverable through the API after a restore, though the pre-restore state can still exist as a version if one was captured beforehand.


### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `notebookId` | path | string | Yes | ID of the notebook that contains the document |
| `nodeId` | path | string | Yes | ID of the document node to restore |
| `versionId` | path | string | Yes | ID of the version to restore from |

### Response



```json
{
  "success": true
}
```


```json
{
  "message": "You do not have permission to restore this document",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "versionId",
      "message": "Caller does not have write access on the document"
    }
  ]
}
```


```json
{
  "message": "Document version not found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "versionId",
      "message": "No version exists with the given ID for this document"
    }
  ]
}
```


```json
{
  "message": "Failed to restore document version",
  "code": "INTERNAL_ERROR",
  "details": [
    {
      "path": "versionId",
      "message": "An unexpected error occurred while writing the restored content"
    }
  ]
}
```



### SDK usage

```ts
const result = await client.notes.versions.restore({
  notebookId: "ntb_01HXY1Z2A3B4C5D6E7F8G9H0J",
  nodeId: "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
  versionId: "vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA",
});
```

```bash
curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXY1Z2A3B4C5D6E7F8G9H0J/nodes/nd_01HXY2A3B4C5D6E7F8G9H0J1KA/versions/vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA/restore" \
  -H "Authorization: Bearer <token>"
```

## Delete a document version

### `DELETE /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions/{versionId}`

Deletes a specific document version. The version is permanently removed and cannot be restored through the API.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `notebookId` | path | string | Yes | ID of the notebook that contains the document |
| `nodeId` | path | string | Yes | ID of the document node |
| `versionId` | path | string | Yes | ID of the version to delete |

### Response



```json
{
  "success": true
}
```


```json
{
  "message": "You do not have permission to delete this document version",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "versionId",
      "message": "Caller does not have write access on the document"
    }
  ]
}
```


```json
{
  "message": "Document version not found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "versionId",
      "message": "No version exists with the given ID for this document"
    }
  ]
}
```



### SDK usage

```ts
const result = await client.notes.versions.delete({
  notebookId: "ntb_01HXY1Z2A3B4C5D6E7F8G9H0J",
  nodeId: "nd_01HXY2A3B4C5D6E7F8G9H0J1KA",
  versionId: "vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA",
});
```

```bash
curl -X DELETE "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXY1Z2A3B4C5D6E7F8G9H0J/nodes/nd_01HXY2A3B4C5D6E7F8G9H0J1KA/versions/vrs_01HXY8K9C2P3N4Q5R6S7T8U9VA" \
  -H "Authorization: Bearer <token>"
```