Notes: Nodes & Documents

Manage notebook nodes (pages, sections, channels, databases, records), read and write document content, export documents, and track read interactions. This page covers the node lifecycle (list, create, update, delete), per-node document operations (read, replace, merge, append), SVG export of drawing blocks, secure HTML export tickets, and per-user “seen” / “opened” timestamps.

All endpoints run inside the notes service container. The base URL follows the template:

https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com

Nodes

`GET /api/v1/notes/notebooks/{notebookId}/nodes`

Returns a paginated list of nodes the user has access to. Filterable by type, parentId, and rootId.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`type`	query	string	No	Filter by node type
`parentId`	query	string	No	Filter by parent node ID
`rootId`	query	string	No	Filter by root node ID
`limit`	query	integer	No	Maximum number of nodes to return. Default: `50`
`offset`	query	integer	No	Number of nodes to skip. Default: `0`

Response

{
  "nodes": [
    {
      "id": "node_8f3a2b1c",
      "type": "page",
      "parentId": "node_root01",
      "attributes": {
        "name": "Project Onboarding",
        "alias": "onboarding",
        "icon": "rocket"
      },
      "createdAt": "2026-01-15T10:22:18.000Z",
      "updatedAt": "2026-02-03T14:05:51.000Z"
    },
    {
      "id": "node_8f3a2b1d",
      "type": "section",
      "parentId": "node_root01",
      "attributes": {
        "name": "Engineering"
      },
      "createdAt": "2026-01-15T10:22:18.000Z",
      "updatedAt": null
    }
  ],
  "total": 142
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    { "path": "notebookId", "message": "Notebook is private" }
  ]
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

SDK usage

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.nodes.list('nb_abc123', { type: 'page', limit: 25 });

`GET /api/v1/notes/notebooks/{notebookId}/nodes/alias/{alias}`

Resolves a page node by its safe alias within the notebook scope.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`alias`	path	string	Yes	The safe URL-style alias of the node

Response

{
  "id": "node_8f3a2b1c",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Project Onboarding",
    "alias": "onboarding",
    "icon": "rocket"
  },
  "createdAt": "2026-01-15T10:22:18.000Z",
  "updatedAt": "2026-02-03T14:05:51.000Z"
}

{
  "message": "Alias must contain only lowercase letters, digits, and dashes.",
  "code": "bad_request",
  "details": [
    { "path": "alias", "message": "Invalid alias format" }
  ]
}

{
  "message": "You do not have access to this notebook.",
  "code": "forbidden",
  "details": []
}

{
  "message": "No node found with alias 'onboarding'.",
  "code": "not_found",
  "details": []
}

SDK usage

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.nodes.getByAlias('nb_abc123', 'onboarding');

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

Returns the full details of a single node by ID.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Response

{
  "id": "node_8f3a2b1c",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Project Onboarding",
    "alias": "onboarding",
    "icon": "rocket"
  },
  "createdAt": "2026-01-15T10:22:18.000Z",
  "updatedAt": "2026-02-03T14:05:51.000Z"
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    { "path": "nodeId", "message": "Node is private" }
  ]
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": [
    { "path": "nodeId", "message": "No node with that ID in this notebook" }
  ]
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

SDK usage

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.nodes.get('nb_abc123', 'node_8f3a2b1c');

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

Returns a paginated list of direct children of the specified node.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The parent node identifier
`limit`	query	integer	No	Maximum number of children to return. Default: `50`
`offset`	query	integer	No	Number of children to skip. Default: `0`

Response

{
  "nodes": [
    {
      "id": "node_8f3a2b1c",
      "type": "page",
      "parentId": "node_root01",
      "attributes": {
        "name": "Project Onboarding",
        "alias": "onboarding"
      },
      "createdAt": "2026-01-15T10:22:18.000Z",
      "updatedAt": "2026-02-03T14:05:51.000Z"
    }
  ],
  "total": 7
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

SDK usage

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.nodes.listChildren('nb_abc123', 'node_root01', { limit: 10 });

`POST /api/v1/notes/notebooks/{notebookId}/nodes`

Creates a new node (section, page, channel, message, database, or record) in the notebook.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier

Request Body

Field	Type	Required	Description
`id`	string	No	Optional client-supplied node ID
`type`	string	Yes	Node type (e.g. `page`, `section`, `channel`, `database`, `record`)
`parentId`	string	No	Identifier of the parent node
`attributes`	object	Yes	Free-form attribute map (e.g. `{ name, alias, icon }`)

{
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Q2 Roadmap",
    "alias": "q2-roadmap",
    "icon": "star"
  }
}

Response

{
  "id": "node_d34db33f",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Q2 Roadmap",
    "alias": "q2-roadmap",
    "icon": "star"
  },
  "createdAt": "2026-03-04T09:00:00.000Z",
  "updatedAt": null
}

{
  "message": "Invalid node type.",
  "code": "bad_request",
  "details": [
    { "path": "type", "message": "Unsupported node type" }
  ]
}

Error Code	Title	Description	Resolution
`bad_request`	Invalid node data	The request body is invalid — missing required fields or unsupported node type	Check the node type is valid and all required attributes are provided

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

{
  "message": "Idempotency key conflict.",
  "code": "bad_request",
  "details": [
    { "path": "id", "message": "A node with this ID already exists" }
  ]
}

Error Code	Title	Description	Resolution
`bad_request`	Idempotency conflict	A different request was already made with the same idempotency key	Use a new idempotency key for a different request

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.nodes.create('nb_abc123', {
  type: 'page',
  parentId: 'node_root01',
  attributes: {
    name: 'Q2 Roadmap',
    alias: 'q2-roadmap',
    icon: 'star',
  },
});

`PATCH /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}`

Updates node attributes (name, description, etc.). type and parentId cannot be changed.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Request Body

Field	Type	Required	Description
`attributes`	object	Yes	Subset of attributes to update (e.g. `{ name, description, icon }`)

{
  "attributes": {
    "name": "Q2 Roadmap (final)",
    "description": "Cross-team roadmap for April–June",
    "icon": "calendar"
  }
}

Response

{
  "id": "node_d34db33f",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Q2 Roadmap (final)",
    "description": "Cross-team roadmap for April–June",
    "icon": "calendar"
  },
  "createdAt": "2026-03-04T09:00:00.000Z",
  "updatedAt": "2026-03-04T09:14:22.000Z"
}

{
  "message": "Cannot change node type.",
  "code": "bad_request",
  "details": [
    { "path": "type", "message": "Type is immutable" }
  ]
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

{
  "message": "Node has been modified since you last read it.",
  "code": "conflict",
  "details": []
}

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.nodes.update('nb_abc123', 'node_8f3a2b1c', {
  attributes: {
    name: 'Q2 Roadmap (final)',
    icon: 'calendar',
  },
});

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

Permanently deletes a node and its associated data (documents, files, reactions).

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Response

{
  "success": true
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.nodes.delete('nb_abc123', 'node_8f3a2b1c');

Documents

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

Retrieves document content for a node. Supports block filtering via blockIds and line range queries via lines.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier
`blockIds`	query	string	No	Comma-separated list of block IDs to return
`lines`	query	string	No	Line range, e.g. `1-50`
`output`	query	string	No	Output format. One of `json`, `md`, `html`
`includeComments`	query	string	No	`none` (default) or `appendix`
`ticket`	query	string	No	Export ticket required for `output=html`

Response

{
  "id": "doc_a1b2c3d4",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading1",
        "content": [
          { "type": "text", "text": "Project Onboarding" }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Welcome to the team. Start with the runbook below." }
        ]
      }
    ]
  },
  "createdAt": "2026-01-15T10:22:18.000Z",
  "createdBy": "user_9f8e7d6c",
  "updatedAt": "2026-02-03T14:05:51.000Z",
  "updatedBy": "user_9f8e7d6c"
}

{
  "message": "Export ticket is missing, expired, or already used.",
  "code": "ticket_invalid",
  "details": [
    { "path": "ticket", "message": "Ticket not provided" }
  ]
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

{
  "message": "Document not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Document not found	No document content exists for this node, or the node type does not support documents	Create document content with putDocument first

SDK usage

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.documents.get('nb_abc123', 'node_8f3a2b1c', {
  output: 'md',
  includeComments: 'none',
});

`PUT /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/document`

Creates a new document or fully replaces an existing document for a node.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Request Body

Field	Type	Required	Description
`content`	object	Yes	Full document content object (ProseMirror-style: `type`, `content`, etc.)

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading1",
        "content": [
          { "type": "text", "text": "Release Notes — v3.4" }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Adds collaborative cursors and inline comments." }
        ]
      }
    ]
  }
}

Response

{
  "id": "doc_a1b2c3d4",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading1",
        "content": [
          { "type": "text", "text": "Release Notes — v3.4" }
        ]
      }
    ]
  },
  "createdAt": "2026-01-15T10:22:18.000Z",
  "createdBy": "user_9f8e7d6c",
  "updatedAt": "2026-03-04T11:02:09.000Z",
  "updatedBy": "user_9f8e7d6c"
}

{
  "message": "Node type does not support documents.",
  "code": "bad_request",
  "details": [
    { "path": "nodeId", "message": "Section nodes are not document-bearing" }
  ]
}

Error Code	Title	Description	Resolution
`bad_request`	Unsupported node type	This node type does not support document content	Only page, channel, and similar node types support documents

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin
`forbidden`	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.documents.put('nb_abc123', 'node_8f3a2b1c', {
  content: {
    type: 'doc',
    content: [
      {
        type: 'heading1',
        content: [{ type: 'text', text: 'Release Notes — v3.4' }],
      },
    ],
  },
});

`PATCH /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/document`

Merges content into an existing document at the top level. Existing blocks are preserved unless overwritten.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Request Body

Field	Type	Required	Description
`content`	object	Yes	Partial document content to merge

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Patched at 11:02 — see changelog." }
        ]
      }
    ]
  }
}

Response

{
  "id": "doc_a1b2c3d4",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Patched at 11:02 — see changelog." }
        ]
      }
    ]
  },
  "createdAt": "2026-01-15T10:22:18.000Z",
  "createdBy": "user_9f8e7d6c",
  "updatedAt": "2026-03-04T11:02:09.000Z",
  "updatedBy": "user_9f8e7d6c"
}

{
  "message": "Node type does not support documents.",
  "code": "bad_request",
  "details": []
}

Error Code	Title	Description	Resolution
`bad_request`	Unsupported node type	This node type does not support document content	Only page, channel, and similar node types support documents

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin
`forbidden`	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

{
  "message": "Document not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Document not found	No document exists for this node — create it with putDocument first	Use putDocument to create the document before patching

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.documents.patch('nb_abc123', 'node_8f3a2b1c', {
  content: {
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [{ type: 'text', text: 'Patched at 11:02 — see changelog.' }],
      },
    ],
  },
});

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/document/append`

Appends one or more blocks to the END of a node’s rich-text document. The server assigns each block’s id, parentId, and index — any client-supplied id, parentId, index, or attrs.id is rejected. If the document does not exist yet, it is created.

Provide either text (a single block from plain text — newlines are preserved as a single literal block) or blocks (flat root blocks), never both. Allowed block types: paragraph, heading1, heading2, heading3, codeBlock, horizontalRule.

Pass X-Idempotency-Key to make retries safe. Reusing the same key with an identical body replays the original response; reusing it with a different body or node returns 409.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier
`X-Idempotency-Key`	header	string	No	Optional idempotency key (max 256 chars). Reusing the same key with an identical request body and node replays the original response; reusing it with a different body or node returns 409.

Request Body

Field	Type	Required	Description
`text`	string	Conditional	Plain text for a single block. Newlines are NOT split — stored as one literal block. Mutually exclusive with `blocks`.
`type`	string	No	Block type for the `text` form. One of `paragraph` (default), `heading1`, `heading2`, `heading3`, `codeBlock`.
`attrs`	object \| null	No	Block-level attributes for the `text` form (e.g. `{ language: "ts" }` for code blocks).
`blocks`	array	Conditional	Flat root block list. Mutually exclusive with `text`. 1–100 items. Each block has `type` (default `paragraph`; allowed: `paragraph`, `heading1`, `heading2`, `heading3`, `codeBlock`, `horizontalRule`), `content` (array of inline `{ type: "text", text, marks }`), and optional `attrs`.

{
  "text": "All hands meeting moved to Thursday at 3 PM.",
  "type": "paragraph"
}

Or, using the blocks form:

{
  "blocks": [
    {
      "type": "heading2",
      "content": [
        { "type": "text", "text": "Agenda" }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Roadmap, hiring, and Q&A." }
      ]
    },
    {
      "type": "horizontalRule"
    }
  ]
}

Response

{
  "id": "doc_a1b2c3d4",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "All hands meeting moved to Thursday at 3 PM." }
        ]
      }
    ]
  },
  "createdAt": "2026-01-15T10:22:18.000Z",
  "createdBy": "user_9f8e7d6c",
  "updatedAt": "2026-03-04T11:30:00.000Z",
  "updatedBy": "user_9f8e7d6c",
  "appendedBlockIds": ["block_91afc2", "block_91afc3"]
}

{
  "message": "This node type does not support documents.",
  "code": "bad_request",
  "details": [
    { "path": "nodeId", "message": "Section nodes are not document-bearing" }
  ]
}

Error Code	Title	Description	Resolution
`bad_request`	Invalid append request	The request body is invalid — provide exactly one of `text` or `blocks`, a non-empty text, an allowed block type, no server-managed fields (id/parentId/index/attrs.id), at most 100 blocks, and content under the size limit. Also returned when the node type does not support documents.	Send a valid append payload to a page (or other document-bearing) node

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin
`forbidden`	Insufficient permissions	User role does not have permission for this action	Request a higher role from the notebook or node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

{
  "message": "Idempotency key already used with a different request.",
  "code": "bad_request",
  "details": [
    { "path": "X-Idempotency-Key", "message": "Key reused with a different body" }
  ]
}

Error Code	Title	Description	Resolution
`bad_request`	Idempotency key conflict	The X-Idempotency-Key was already used with a different request body or node	Use a fresh X-Idempotency-Key for a different append, or resend the identical request to replay

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.documents.appendDocument(
  'nb_abc123',
  'node_8f3a2b1c',
  { text: 'All hands meeting moved to Thursday at 3 PM.', type: 'paragraph' },
  { XIdempotencyKey: 'append-2026-03-04-001' },
);

Export

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/export-ticket`

Creates a short-lived export ticket for static HTML document delivery. The ticket is required to fetch the document with output=html.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Request Body

Field	Type	Required	Description
`output`	string	No	Output format. Default: `"html"`
`includeComments`	string	No	`none` (default) or `appendix`
`includeBackground`	boolean	No	Whether to include background styles. Default: `true`
`themeMode`	string	No	`light` or `dark`. Default: `"dark"`
`themeId`	string \| null	No	Optional theme identifier (max 64 chars)
`themeVariables`	object	No	Map of theme variable overrides (string → string)
`fileName`	string	No	Suggested file name (max 128 chars)

{
  "output": "html",
  "includeComments": "appendix",
  "themeMode": "light",
  "fileName": "Onboarding.html"
}

Response

{
  "ticket": "tk_8f3a2b1cQ6yZ",
  "expiresAt": "2026-03-04T11:45:00.000Z",
  "usesRemaining": 3
}

{
  "message": "You do not have permission to export this node.",
  "code": "forbidden",
  "details": []
}

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

SDK usage

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.documents.createExportTicket('nb_abc123', 'node_8f3a2b1c', {
  output: 'html',
  includeComments: 'appendix',
  themeMode: 'light',
  fileName: 'Onboarding.html',
});

`GET /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/blocks/{blockId}/svg`

Renders a drawing block as an SVG image. Supports optional background color and scale factor.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier
`blockId`	path	string	Yes	The drawing block identifier
`bg`	query	string	No	Background color, e.g. `transparent`, `#ffffff`
`scale`	query	number	No	Scale factor applied to the rendered SVG

Response

Content-Type: image/svg+xml

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 600 400">
  <rect width="600" height="400" fill="#ffffff"/>
  <path d="M 50 200 Q 300 50 550 200" stroke="#111" stroke-width="3" fill="none"/>
</svg>

SDK usage

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.documents.exportBlockSvg('nb_abc123', 'node_8f3a2b1c', 'block_d12', {
  bg: 'transparent',
  scale: 2,
});

Interactions

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/interactions/opened`

Records that the current user has opened the node. Tracks first and last opened timestamps.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Request Body

Field	Type	Required	Description
`openedAt`	string	No	ISO-8601 timestamp; defaults to server time if omitted

{
  "openedAt": "2026-03-04T11:02:09.000Z"
}

Response

{
  "nodeId": "node_8f3a2b1c",
  "collaboratorId": "user_9f8e7d6c",
  "firstSeenAt": "2026-02-01T08:11:00.000Z",
  "lastSeenAt": "2026-03-04T11:02:09.000Z",
  "firstOpenedAt": "2026-03-04T11:02:09.000Z",
  "lastOpenedAt": "2026-03-04T11:02:09.000Z"
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

{
  "message": "Idempotency key conflict.",
  "code": "bad_request",
  "details": []
}

Error Code	Title	Description	Resolution
`bad_request`	Idempotency conflict	A different request was already made with the same idempotency key	Use a new idempotency key for a different request

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.interactions.markOpened('nb_abc123', 'node_8f3a2b1c', {
  openedAt: '2026-03-04T11:02:09.000Z',
});

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/interactions/seen`

Records that the current user has seen the node. Tracks first and last seen timestamps.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier

Request Body

Field	Type	Required	Description
`seenAt`	string	No	ISO-8601 timestamp; defaults to server time if omitted

{
  "seenAt": "2026-03-04T11:01:55.000Z"
}

Response

{
  "nodeId": "node_8f3a2b1c",
  "collaboratorId": "user_9f8e7d6c",
  "firstSeenAt": "2026-02-01T08:11:00.000Z",
  "lastSeenAt": "2026-03-04T11:01:55.000Z",
  "firstOpenedAt": "2026-03-04T11:02:09.000Z",
  "lastOpenedAt": "2026-03-04T11:02:09.000Z"
}

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": []
}

Error Code	Title	Description	Resolution
`forbidden`	Access denied	User does not have permission to access this node	Check collaborator list or request access from the node admin

{
  "message": "Node not found.",
  "code": "not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`not_found`	Node not found	No node exists with the provided ID in this notebook	Verify node ID using listNodes or listNodeChildren

{
  "message": "Idempotency key conflict.",
  "code": "bad_request",
  "details": []
}

Error Code	Title	Description	Resolution
`bad_request`	Idempotency conflict	A different request was already made with the same idempotency key	Use a new idempotency key for a different request

{
  "message": "An unexpected error occurred.",
  "code": "unknown",
  "details": []
}

Error Code	Title	Description	Resolution
`unknown`	Internal server error	An unexpected error occurred while processing the request	Retry the request; if it persists, contact support

SDK usage

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.interactions.markSeen('nb_abc123', 'node_8f3a2b1c', {
  seenAt: '2026-03-04T11:01:55.000Z',
});