Notes: Document Versions

The Notes service captures and manages document version snapshots. Every edit cycle produces a new revision; you can list, inspect, restore, or remove those revisions through the endpoints on this page. Use these routes when you need to audit history, undo accidental edits, or build a branching workflow on top of notebook content.

All endpoints are scoped to a notebook ({notebookId}) and a document node ({nodeId}). Requests target the per-container Notes service at https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com.

List document versions

Returns every version recorded for a document, ordered by revision descending. Use cursor pagination via limit and offset.

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook that owns the document.
nodeId	path	string	Yes	Identifier 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 from the start of the result set. Default: 0.

cURL

curl -G \
  "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.versions.list(notebookId, nodeId, { limit: 20, offset: 0 });

200

{
  "versions": [
    {
      "id": "v_8f3a2c1e9b0d4f5a",
      "documentId": "doc_77a1b3c5d9e2f4a6",
      "revision": 12,
      "createdAt": "2024-03-15T10:30:00.000Z",
      "createdBy": "user_alice"
    },
    {
      "id": "v_8f3a2c1e9b0d4f5b",
      "documentId": "doc_77a1b3c5d9e2f4a6",
      "revision": 11,
      "createdAt": "2024-03-14T16:22:11.000Z",
      "createdBy": "user_alice"
    }
  ],
  "total": 12
}

403

{
  "message": "Forbidden",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "notebookId",
      "message": "You do not have access to this notebook."
    }
  ]
}

404

{
  "message": "Not Found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "nodeId",
      "message": "Document node does not exist in the specified notebook."
    }
  ]
}

Get a document version

Retrieves a single version, including the full document content snapshot at that revision.

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook that owns the document.
nodeId	path	string	Yes	Identifier of the document node.
versionId	path	string	Yes	Identifier of the version to retrieve.

cURL

curl \
  "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions/{versionId}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.versions.get(notebookId, nodeId, versionId);

200

{
  "id": "v_8f3a2c1e9b0d4f5a",
  "documentId": "doc_77a1b3c5d9e2f4a6",
  "revision": 12,
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "text": "Quarterly planning notes for Q2."
      }
    ]
  },
  "createdAt": "2024-03-15T10:30:00.000Z",
  "createdBy": "user_alice"
}

403

{
  "message": "Forbidden",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "notebookId",
      "message": "You do not have access to this notebook."
    }
  ]
}

404

{
  "message": "Not Found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "versionId",
      "message": "Version does not exist for the specified document."
    }
  ]
}

Create a document version

Captures the current document content as a new immutable version snapshot. The new revision number is one greater than the most recent existing revision.

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook that owns the document.
nodeId	path	string	Yes	Identifier of the document node.

cURL

curl -X POST \
  "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.versions.create(notebookId, nodeId);

200

{
  "id": "v_8f3a2c1e9b0d4f5c",
  "documentId": "doc_77a1b3c5d9e2f4a6",
  "revision": 13,
  "createdAt": "2024-03-16T09:15:00.000Z",
  "createdBy": "user_alice"
}

403

{
  "message": "Forbidden",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "notebookId",
      "message": "You do not have permission to snapshot this document."
    }
  ]
}

404

{
  "message": "Not Found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "nodeId",
      "message": "Document node does not exist in the specified notebook."
    }
  ]
}

Restore a document version

Reverts the document’s current content to the content recorded in the specified version. The restore itself produces a new version, so history is preserved.

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook that owns the document.
nodeId	path	string	Yes	Identifier of the document node.
versionId	path	string	Yes	Identifier of the version to restore.

cURL

curl -X POST \
  "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions/{versionId}/restore" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.versions.restore(notebookId, nodeId, versionId);

200

{
  "success": true
}

403

{
  "message": "Forbidden",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "notebookId",
      "message": "You do not have permission to modify documents in this notebook."
    }
  ]
}

404

{
  "message": "Not Found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "versionId",
      "message": "Version does not exist for the specified document."
    }
  ]
}

500

{
  "message": "Internal Server Error",
  "code": "INTERNAL_ERROR",
  "details": [
    {
      "path": "versionId",
      "message": "Restore failed while writing to document storage."
    }
  ]
}

Delete a document version

Removes a single version from the document’s history. The current document content is not affected.

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook that owns the document.
nodeId	path	string	Yes	Identifier of the document node.
versionId	path	string	Yes	Identifier of the version to delete.

cURL

curl -X DELETE \
  "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/versions/{versionId}" \
  -H "Authorization: Bearer $HOODY_TOKEN"

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notes.versions.delete(notebookId, nodeId, versionId);

200

{
  "success": true
}

403

{
  "message": "Forbidden",
  "code": "FORBIDDEN",
  "details": [
    {
      "path": "notebookId",
      "message": "You do not have permission to delete versions in this notebook."
    }
  ]
}

404

{
  "message": "Not Found",
  "code": "NOT_FOUND",
  "details": [
    {
      "path": "versionId",
      "message": "Version does not exist for the specified document."
    }
  ]
}

Note

Deletion is permanent and only removes the targeted version. To recover previous content after a delete, use the restore endpoint against any remaining version. Restoring produces a new revision rather than resurrecting the deleted one.