Notes: Nodes & Documents

The Notes service models content as a tree of nodes inside a notebook: sections, pages, channels, databases, and records. The endpoints on this page let you list, create, read, update, and delete nodes; read, write, merge, and append document content on page-bearing nodes; export content as HTML or SVG; and record per-user open/seen interactions.

Base URL template used by all cURL examples below:

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

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
`type`	query	string	No	Restrict results to a node type (for example `page`, `section`)
`parentId`	query	string	No	Restrict to direct children of the given node
`rootId`	query	string	No	Restrict to descendants of the given root node
`limit`	query	integer	No	Maximum number of results (default `50`)
`offset`	query	integer	No	Number of results to skip (default `0`)
`notebookId`	path	string	Yes	Notebook identifier

curl -X GET "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes?type=page&limit=25" \
  -H "Authorization: Bearer <token>"

await client.notes.nodes.list("nb_abc123", { type: "page", limit: 25 });

Response

{
  "nodes": [
    {
      "id": "node_root01",
      "type": "section",
      "parentId": null,
      "attributes": {
        "name": "Onboarding",
        "alias": "onboarding"
      }
    },
    {
      "id": "node_8f3a2b",
      "type": "page",
      "parentId": "node_root01",
      "attributes": {
        "name": "Welcome",
        "alias": "welcome"
      }
    }
  ],
  "total": 24
}

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

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Examples

cURL
SDK

curl -X GET "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b" \
  -H "Authorization: Bearer <token>"

await client.notes.nodes.get("nb_abc123", "node_8f3a2b");

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Welcome",
    "alias": "welcome",
    "description": "First page new collaborators see",
    "icon": "wave"
  },
  "createdAt": "2026-01-10T08:00:00.000Z",
  "createdBy": "user_abc123",
  "updatedAt": "2026-01-15T11:24:00.000Z",
  "updatedBy": "user_def456"
}

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

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": "node_8f3a2b" }
  ]
}

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

`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	Notebook identifier
`alias`	path	string	Yes	Safe alias of the page node

Examples

cURL
SDK

curl -X GET "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/alias/onboarding" \
  -H "Authorization: Bearer <token>"

await client.notes.nodes.getByAlias("nb_abc123", "onboarding");

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Welcome",
    "alias": "welcome"
  },
  "createdAt": "2026-01-10T08:00:00.000Z",
  "createdBy": "user_abc123",
  "updatedAt": "2026-01-15T11:24:00.000Z",
  "updatedBy": "user_def456"
}

{
  "message": "Invalid alias format.",
  "code": "bad_request",
  "details": [
    { "path": "alias", "message": "on boarding" }
  ]
}

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

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

`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
`limit`	query	integer	No	Maximum number of results (default `50`)
`offset`	query	integer	No	Number of results to skip (default `0`)
`notebookId`	path	string	Yes	Notebook identifier
`nodeId`	path	string	Yes	Parent node identifier

Examples

cURL
SDK

curl -X GET "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_root01/children?limit=10" \
  -H "Authorization: Bearer <token>"

await client.notes.nodes.listChildren("nb_abc123", "node_root01", { limit: 10 });

Response

{
  "nodes": [
    {
      "id": "node_p1",
      "type": "page",
      "parentId": "node_root01",
      "attributes": { "name": "Step 1" }
    },
    {
      "id": "node_p2",
      "type": "page",
      "parentId": "node_root01",
      "attributes": { "name": "Step 2" }
    }
  ],
  "total": 6
}

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

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": "node_root01" }
  ]
}

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

`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	Notebook identifier

Request Body

Field	Type	Required	Description
`id`	string	No	Optional client-supplied node ID
`type`	string	Yes	Node type (for example `page`, `section`, `channel`, `database`)
`parentId`	string	No	Parent node ID; omit to create a top-level node
`attributes`	object	Yes	Free-form attributes object (`name`, `alias`, `icon`, `description`, etc.)

Examples

cURL
SDK

curl -X POST "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "page",
    "parentId": "node_root01",
    "attributes": {
      "name": "Onboarding Checklist",
      "alias": "onboarding",
      "icon": "check"
    }
  }'

await client.notes.nodes.create("nb_abc123", {
  type: "page",
  parentId: "node_root01",
  attributes: {
    name: "Onboarding Checklist",
    alias: "onboarding",
    icon: "check"
  }
});

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Onboarding Checklist",
    "alias": "onboarding",
    "icon": "check"
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "createdBy": "user_abc123"
}

{
  "message": "Invalid node type.",
  "code": "bad_request",
  "details": [
    { "path": "type", "message": "unknown 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": [
    { "path": "notebookId", "message": "nb_abc123" }
  ]
}

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": "Idempotency-Key", "message": "key_123" }
  ]
}

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Request Body

Field	Type	Required	Description
`attributes`	object	Yes	Free-form attributes object containing the fields to update

Examples

cURL
SDK

curl -X PATCH "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "name": "Welcome (renamed)",
      "description": "Updated onboarding landing page"
    }
  }'

await client.notes.nodes.update("nb_abc123", "node_8f3a2b", {
  attributes: {
    name: "Welcome (renamed)",
    description: "Updated onboarding landing page"
  }
});

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Welcome (renamed)",
    "alias": "welcome",
    "description": "Updated onboarding landing page"
  },
  "updatedAt": "2026-01-16T14:22:11.000Z",
  "updatedBy": "user_def456"
}

{
  "message": "Attribute cannot be changed.",
  "code": "bad_request",
  "details": [
    { "path": "type", "message": "type is immutable" }
  ]
}

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

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": "node_8f3a2b" }
  ]
}

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": "Concurrent modification detected.",
  "code": "conflict",
  "details": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

{
  "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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Examples

cURL
SDK

curl -X DELETE "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b" \
  -H "Authorization: Bearer <token>"

await client.notes.nodes.delete("nb_abc123", "node_8f3a2b");

Response

{
  "success": true
}

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

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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

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
`blockIds`	query	string	No	Comma-separated list of block IDs to include
`lines`	query	string	No	Line range expression (for example `1-10`)
`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`
`notebookId`	path	string	Yes	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Examples

cURL
SDK

curl -X GET "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/document?output=md&includeComments=none" \
  -H "Authorization: Bearer <token>"

await client.notes.documents.get("nb_abc123", "node_8f3a2b", {
  output: "md",
  includeComments: "none"
});

Response

{
  "id": "doc_8f3a2b1c9d",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [
          { "type": "text", "text": "Onboarding" }
        ]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Welcome to the team." }
        ]
      }
    ]
  },
  "createdAt": "2026-01-10T08:00:00.000Z",
  "createdBy": "user_abc123",
  "updatedAt": "2026-01-16T14:22:11.000Z",
  "updatedBy": "user_def456"
}

{
  "message": "Missing or invalid export ticket.",
  "code": "unauthorized",
  "details": [
    { "path": "ticket", "message": "required for output=html" }
  ]
}

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

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Request Body

Field	Type	Required	Description
`content`	object	Yes	Full ProseMirror-style document tree (replaces the existing content)

Examples

cURL
SDK

curl -X PUT "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/document" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "heading",
          "attrs": { "level": 1 },
          "content": [{ "type": "text", "text": "Welcome" }]
        },
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Hello, team." }]
        }
      ]
    }
  }'

await client.notes.documents.put("nb_abc123", "node_8f3a2b", {
  content: {
    type: "doc",
    content: [
      {
        type: "heading",
        attrs: { level: 1 },
        content: [{ type: "text", text: "Welcome" }]
      },
      {
        type: "paragraph",
        content: [{ type: "text", text: "Hello, team." }]
      }
    ]
  }
});

Response

{
  "id": "doc_8f3a2b1c9d",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 1 },
        "content": [{ "type": "text", "text": "Welcome" }]
      },
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Hello, team." }]
      }
    ]
  },
  "createdAt": "2026-01-10T08:00:00.000Z",
  "createdBy": "user_abc123",
  "updatedAt": "2026-01-16T14:22:11.000Z",
  "updatedBy": "user_def456"
}

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

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Request Body

Field	Type	Required	Description
`content`	object	Yes	Partial ProseMirror-style document tree to merge at the top level

Examples

cURL
SDK

curl -X PATCH "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/document" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "attrs": { "id": "block_a1b2c3" },
          "content": [{ "type": "text", "text": "Updated paragraph." }]
        }
      ]
    }
  }'

await client.notes.documents.patch("nb_abc123", "node_8f3a2b", {
  content: {
    type: "doc",
    content: [
      {
        type: "paragraph",
        attrs: { id: "block_a1b2c3" },
        content: [{ type: "text", text: "Updated paragraph." }]
      }
    ]
  }
});

Response

{
  "id": "doc_8f3a2b1c9d",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "attrs": { "id": "block_a1b2c3" },
        "content": [{ "type": "text", "text": "Updated paragraph." }]
      }
    ]
  },
  "createdAt": "2026-01-10T08:00:00.000Z",
  "createdBy": "user_abc123",
  "updatedAt": "2026-01-16T14:22:11.000Z",
  "updatedBy": "user_def456"
}

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

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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

`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 id, parentId, and index — any client-supplied id, parentId, or index (including attrs.id) is rejected. Provide either text (a single block from plain text; newlines are NOT split — the text is stored as one literal block) OR blocks (flat root blocks), never both. If the document does not exist yet it is created. Pass X-Idempotency-Key to make retries safe (a repeated key plus identical body replays the original response; a different body with the same key returns 409). Appendable block types: paragraph, heading1, heading2, heading3, codeBlock, horizontalRule.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Notebook identifier
`nodeId`	path	string	Yes	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

The body is one of two shapes (never both).

Shape A — plain text (single block):

Field	Type	Required	Description
`text`	string	Yes	Plain text content (newlines are not split, the text becomes one literal block)
`type`	string	No	Block type; one of `paragraph`, `heading1`, `heading2`, `heading3`, `codeBlock` (default `paragraph`)
`attrs`	object \| null	No	Optional block attributes

Shape B — explicit blocks (flat root blocks):

Field	Type	Required	Description
`blocks`	array	Yes	Array of 1 to 100 root blocks to append
`blocks[].type`	string	No	One of `paragraph`, `heading1`, `heading2`, `heading3`, `codeBlock`, `horizontalRule` (default `paragraph`)
`blocks[].content`	array	No	Inline content nodes; each node has `type: "text"`, `text`, and optional `marks`
`blocks[].attrs`	object \| null	No	Optional block attributes

Examples

curl -X POST "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/document/append" \
  -H "Authorization: Bearer <token>" \
  -H "X-Idempotency-Key: key_123" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Second section begins here.",
    "type": "heading1"
  }'

curl -X POST "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/document/append" \
  -H "Authorization: Bearer <token>" \
  -H "X-Idempotency-Key: key_124" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Hello world." }
        ]
      },
      {
        "type": "horizontalRule"
      }
    ]
  }'

await client.notes.documents.appendDocument(
  "nb_abc123",
  "node_8f3a2b",
  {
    blocks: [
      {
        type: "paragraph",
        content: [{ type: "text", text: "Hello world." }]
      },
      { type: "horizontalRule" }
    ]
  },
  { XIdempotencyKey: "key_124" }
);

Response

{
  "id": "doc_8f3a2b1c9d",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "attrs": { "id": "block_a1b2c3" },
        "content": [{ "type": "text", "text": "Hello world." }]
      },
      {
        "type": "horizontalRule",
        "attrs": { "id": "block_d4e5f6" }
      }
    ]
  },
  "createdAt": "2026-01-10T08:00:00.000Z",
  "createdBy": "user_abc123",
  "updatedAt": "2026-01-16T14:22:11.000Z",
  "updatedBy": "user_def456",
  "appendedBlockIds": ["block_a1b2c3", "block_d4e5f6"]
}

{
  "message": "This node type does not support documents.",
  "code": "bad_request",
  "details": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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 access to this node.",
  "code": "forbidden",
  "details": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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": [
    { "path": "nodeId", "message": "node_8f3a2b" }
  ]
}

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_124" }
  ]
}

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

`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 output=html from getDocument.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Request Body

Field	Type	Required	Default	Description
`output`	string	No	`"html"`	Output format; only `"html"` is supported
`includeComments`	string	No	`"none"`	`none` or `appendix`
`includeBackground`	boolean	No	`true`	Include the page background in the export
`themeMode`	string	No	`"dark"`	`light` or `dark`
`themeId`	string \| null	No	—	Optional theme identifier (max 64 chars)
`themeVariables`	object	No	—	Map of theme variable name to string value
`fileName`	string	No	—	Suggested file name for the export (max 128 chars)

Examples

cURL
SDK

curl -X POST "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/export-ticket" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "output": "html",
    "includeComments": "appendix",
    "themeMode": "light",
    "fileName": "Onboarding.html"
  }'

await client.notes.documents.createExportTicket("nb_abc123", "node_8f3a2b", {
  output: "html",
  includeComments: "appendix",
  themeMode: "light",
  fileName: "Onboarding.html"
});

Response

{
  "ticket": "tkt_4f1a2b3c8d9e",
  "expiresAt": "2026-01-15T11:00:00.000Z",
  "usesRemaining": 5
}

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

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

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

Renders a drawing block as an SVG image. Supports an optional background color and scale factor. The response is a raw image/svg+xml payload.

Parameters

Name	In	Type	Required	Description
`bg`	query	string	No	Background color (for example `"transparent"`, `"#ffffff"`)
`scale`	query	number	No	Render scale factor
`notebookId`	path	string	Yes	Notebook identifier
`nodeId`	path	string	Yes	Node identifier
`blockId`	path	string	Yes	Drawing block identifier

Examples

cURL
SDK

curl -X GET "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/blocks/block_d12/svg?bg=transparent&scale=2" \
  -H "Authorization: Bearer <token>"

await client.notes.documents.exportBlockSvg(
  "nb_abc123",
  "node_8f3a2b",
  "block_d12",
  { bg: "transparent", scale: 2 }
);

Response

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300">
  <rect width="100%" height="100%" fill="transparent" />
  <path d="M10 80 Q 95 10 180 80 T 390 80" stroke="#222" fill="none" stroke-width="2" />
</svg>

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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Request Body

Field	Type	Required	Description
`openedAt`	string	No	Optional ISO 8601 timestamp; defaults to the current server time

Examples

cURL
SDK

curl -X POST "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/interactions/opened" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

await client.notes.interactions.markOpened("nb_abc123", "node_8f3a2b", {});

Response

{
  "nodeId": "node_8f3a2b",
  "collaboratorId": "user_abc123",
  "firstSeenAt": null,
  "lastSeenAt": null,
  "firstOpenedAt": "2026-01-15T10:30:00.000Z",
  "lastOpenedAt": "2026-01-15T10:30:00.000Z"
}

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

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": "node_8f3a2b" }
  ]
}

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": [
    { "path": "Idempotency-Key", "message": "key_456" }
  ]
}

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier

Request Body

Field	Type	Required	Description
`seenAt`	string	No	Optional ISO 8601 timestamp; defaults to the current server time

Examples

cURL
SDK

curl -X POST "https://proj_demo1-cont_main-notes-1.us-east-1.containers.hoody.icu/api/v1/notes/notebooks/nb_abc123/nodes/node_8f3a2b/interactions/seen" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

await client.notes.interactions.markSeen("nb_abc123", "node_8f3a2b", {});

Response

{
  "nodeId": "node_8f3a2b",
  "collaboratorId": "user_abc123",
  "firstSeenAt": "2026-01-15T10:29:55.000Z",
  "lastSeenAt": "2026-01-15T10:29:55.000Z",
  "firstOpenedAt": null,
  "lastOpenedAt": null
}

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

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": "node_8f3a2b" }
  ]
}

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": [
    { "path": "Idempotency-Key", "message": "key_789" }
  ]
}

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