Notes: Nodes & Documents

Manage notebook nodes (sections, pages, channels, databases, records) and their associated rich-text documents. These endpoints cover node CRUD, alias resolution, child traversal, document read/write, idempotent block append, HTML export tickets, drawing-block SVG rendering, and user interaction tracking (open/seen events).

Use these endpoints when building editor surfaces, content importers, automated doc pipelines, or analytics dashboards that need to read or mutate notebook content.

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	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	Page size (default `50`)
`offset`	query	integer	No	Page offset (default `0`)

SDK Usage

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

Response

{
  "nodes": [
    {
      "id": "node_8f3a2b",
      "type": "page",
      "parentId": "node_root01",
      "attributes": {
        "name": "Onboarding checklist",
        "alias": "onboarding",
        "icon": "📋"
      },
      "createdAt": "2025-01-12T09:21:00.000Z",
      "updatedAt": "2025-03-04T14:08:00.000Z"
    },
    {
      "id": "node_4c91de",
      "type": "section",
      "parentId": "node_root01",
      "attributes": {
        "name": "Engineering"
      },
      "createdAt": "2025-01-10T11:02:00.000Z",
      "updatedAt": "2025-01-10T11:02:00.000Z"
    }
  ],
  "total": 2
}

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

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

SDK Usage

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

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Onboarding checklist",
    "alias": "onboarding",
    "icon": "📋",
    "description": "First-day steps for new hires"
  },
  "createdAt": "2025-01-12T09:21:00.000Z",
  "createdBy": "user_alice",
  "updatedAt": "2025-03-04T14:08:00.000Z",
  "updatedBy": "user_bob"
}

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

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

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	Node alias

SDK Usage

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

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Onboarding checklist",
    "alias": "onboarding"
  },
  "createdAt": "2025-01-12T09:21:00.000Z",
  "updatedAt": "2025-03-04T14:08:00.000Z"
}

{
  "message": "Invalid alias format.",
  "code": "bad_request"
}

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

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Parent node identifier
`limit`	query	integer	No	Page size (default `50`)
`offset`	query	integer	No	Page offset (default `0`)

SDK Usage

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

Response

{
  "nodes": [
    {
      "id": "node_8f3a2b",
      "type": "page",
      "parentId": "node_root01",
      "attributes": { "name": "Onboarding checklist" },
      "createdAt": "2025-01-12T09:21:00.000Z"
    },
    {
      "id": "node_4c91de",
      "type": "section",
      "parentId": "node_root01",
      "attributes": { "name": "Engineering" },
      "createdAt": "2025-01-10T11:02:00.000Z"
    }
  ],
  "total": 2
}

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

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

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

Name	Type	Required	Description
`id`	string	No	Optional client-supplied node ID
`type`	string	Yes	Node type (e.g. `page`, `section`, `channel`, `database`, `record`, `message`)
`parentId`	string	No	Parent node ID
`attributes`	object	Yes	Type-specific attributes (e.g. `name`, `description`, `alias`, `icon`)

{
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Release notes",
    "alias": "release-notes",
    "icon": "🚀",
    "description": "Track weekly product releases"
  }
}

SDK Usage

await client.notes.nodes.create("nb_abc123", {
  type: "page",
  parentId: "node_root01",
  attributes: { name: "Release notes", alias: "release-notes" }
});

Response

{
  "id": "node_77ab2e",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Release notes",
    "alias": "release-notes",
    "icon": "🚀"
  },
  "createdAt": "2025-04-01T08:00:00.000Z",
  "createdBy": "user_alice"
}

{
  "message": "Invalid node type.",
  "code": "bad_request"
}

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

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

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

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

Name	Type	Required	Description
`attributes`	object	Yes	Partial attribute map to merge (e.g. `name`, `description`, `icon`)

{
  "attributes": {
    "name": "Release notes (Q2)",
    "description": "Weekly product release notes for Q2 2025"
  }
}

SDK Usage

await client.notes.nodes.update("nb_abc123", "node_8f3a2b", {
  attributes: { name: "Release notes (Q2)", description: "Weekly product release notes for Q2 2025" }
});

Response

{
  "id": "node_8f3a2b",
  "type": "page",
  "parentId": "node_root01",
  "attributes": {
    "name": "Release notes (Q2)",
    "description": "Weekly product release notes for Q2 2025"
  },
  "createdAt": "2025-01-12T09:21:00.000Z",
  "updatedAt": "2025-04-01T08:42:00.000Z",
  "updatedBy": "user_alice"
}

{
  "message": "Cannot change node type or parent.",
  "code": "bad_request"
}

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

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

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": "Conflict updating node.",
  "code": "conflict"
}

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

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

SDK Usage

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

Response

{
  "success": true
}

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

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

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

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.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Notebook identifier
`nodeId`	path	string	Yes	Node identifier
`blockIds`	query	string	No	Comma-separated list of block IDs to fetch
`lines`	query	string	No	Line range, e.g. `0-50`
`output`	query	string	No	Output format: `json`, `md`, or `html`
`includeComments`	query	string	No	`none` (default) or `appendix`
`ticket`	query	string	No	Export ticket (required when `output=html`)

SDK Usage

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

Response

{
  "id": "doc_77ab2e",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading1",
        "content": [{ "type": "text", "text": "Onboarding checklist" }]
      },
      {
        "type": "paragraph",
        "content": [
          { "type": "text", "text": "Welcome to the team — start here." }
        ]
      }
    ]
  },
  "createdAt": "2025-01-12T09:21:00.000Z",
  "createdBy": "user_alice",
  "updatedAt": "2025-03-04T14:08:00.000Z",
  "updatedBy": "user_bob"
}

{
  "message": "Missing or invalid export ticket.",
  "code": "unauthorized"
}

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

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

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

Name	Type	Required	Description
`content`	object	Yes	Full document content tree (block tree)

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading1",
        "content": [{ "type": "text", "text": "Release notes" }]
      },
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Initial cut." }]
      }
    ]
  }
}

SDK Usage

await client.notes.documents.put("nb_abc123", "node_8f3a2b", {
  content: {
    type: "doc",
    content: [
      { type: "heading1", content: [{ type: "text", text: "Release notes" }] }
    ]
  }
});

Response

{
  "id": "doc_77ab2e",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "heading1",
        "content": [{ "type": "text", "text": "Release notes" }]
      }
    ]
  },
  "createdAt": "2025-04-01T08:00:00.000Z",
  "createdBy": "user_alice",
  "updatedAt": "2025-04-01T08:00:00.000Z",
  "updatedBy": "user_alice"
}

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

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

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

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

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

Name	Type	Required	Description
`content`	object	Yes	Partial content to merge into the top-level document

{
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Added a new paragraph on 2025-04-02." }]
      }
    ]
  }
}

SDK Usage

await client.notes.documents.patch("nb_abc123", "node_8f3a2b", {
  content: {
    type: "doc",
    content: [
      { type: "paragraph", content: [{ type: "text", text: "Added a new paragraph." }] }
    ]
  }
});

Response

{
  "id": "doc_77ab2e",
  "content": {
    "type": "doc",
    "content": [
      { "type": "heading1", "content": [{ "type": "text", "text": "Release notes" }] },
      { "type": "paragraph", "content": [{ "type": "text", "text": "Added a new paragraph." }] }
    ]
  },
  "createdAt": "2025-04-01T08:00:00.000Z",
  "createdBy": "user_alice",
  "updatedAt": "2025-04-02T10:14:00.000Z",
  "updatedBy": "user_bob"
}

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

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

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

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

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 values (including attrs.id) are rejected.

You must send exactly one of:

text — a single block from plain text. Newlines are not split; the text is stored as one literal block.
blocks — an array of 1–100 flat root blocks.

If the document does not exist yet, it is created. Pass X-Idempotency-Key to make retries safe: a repeated key + identical body replays the original response; a different body with the same key returns 409.

Allowed 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

You must provide one of these two shapes:

Shape A — plain text block:

Name	Type	Required	Description
`text`	string	Yes	Non-empty plain text for a single block
`type`	string	No	Block type — `paragraph` (default), `heading1`, `heading2`, `heading3`, or `codeBlock`
`attrs`	object \| null	No	Block-level attributes (e.g. language for `codeBlock`)

{
  "text": "This change went live on April 2nd.",
  "type": "paragraph"
}

Shape B — array of blocks:

Name	Type	Required	Description
`blocks`	array	Yes	1–100 flat root blocks. Each block has `type` (`paragraph`, `heading1`, `heading2`, `heading3`, `codeBlock`, `horizontalRule`), `content` (array of `{ type: "text", text, marks }`), and optional `attrs`.

{
  "blocks": [
    {
      "type": "heading2",
      "content": [{ "type": "text", "text": "April 2nd updates" }]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "Shipped the new export pipeline." }
      ]
    },
    { "type": "horizontalRule" }
  ]
}

SDK Usage

await client.notes.documents.appendDocument(
  "nb_abc123",
  "node_8f3a2b",
  {
    text: "This change went live on April 2nd.",
    type: "paragraph"
  },
  { XIdempotencyKey: "key_123" }
);

Response

{
  "id": "doc_77ab2e",
  "content": {
    "type": "doc",
    "content": [
      { "type": "heading1", "content": [{ "type": "text", "text": "Release notes" }] },
      { "type": "paragraph", "content": [{ "type": "text", "text": "Initial cut." }] },
      { "type": "paragraph", "content": [{ "type": "text", "text": "This change went live on April 2nd." }] }
    ]
  },
  "createdAt": "2025-04-01T08:00:00.000Z",
  "createdBy": "user_alice",
  "updatedAt": "2025-04-02T10:14:00.000Z",
  "updatedBy": "user_alice",
  "appendedBlockIds": ["block_d12", "block_d13"]
}

{
  "message": "This node type does not support documents.",
  "code": "bad_request"
}

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

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

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

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

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. Ticket is required to fetch output=html.

Parameters

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

Request Body

Name	Type	Required	Description
`output`	string	No	Output format (default `"html"`)
`includeComments`	string	No	`none` (default) or `appendix`
`includeBackground`	boolean	No	Include page background in export (default `true`)
`themeMode`	string	No	`light` or `dark` (default `"dark"`)
`themeId`	string \| null	No	Theme identifier (max 64 chars)
`themeVariables`	object	No	Map of theme variable name to string value
`fileName`	string	No	Suggested download filename (max 128 chars)

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

SDK Usage

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

Response

{
  "ticket": "tkt_8f4a2c91",
  "expiresAt": "2025-04-02T09:30:00.000Z",
  "usesRemaining": 3
}

{
  "message": "You do not have permission to export this document.",
  "code": "forbidden"
}

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

`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	Notebook identifier
`nodeId`	path	string	Yes	Node identifier
`blockId`	path	string	Yes	Drawing block identifier
`bg`	query	string	No	Background color (e.g. `transparent`, `#ffffff`)
`scale`	query	number	No	Scale factor (e.g. `2` for 2× resolution)

SDK Usage

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

Response

Returns an image/svg+xml body containing the rendered drawing.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 600">
  <!-- Drawing strokes and shapes rendered here -->
</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

Name	Type	Required	Description
`openedAt`	string	No	ISO timestamp of the open event (defaults to server time)

{
  "openedAt": "2025-04-02T10:14:00.000Z"
}

SDK Usage

await client.notes.interactions.markOpened("nb_abc123", "node_8f3a2b", {
  openedAt: "2025-04-02T10:14:00.000Z"
});

Response

{
  "nodeId": "node_8f3a2b",
  "collaboratorId": "user_bob",
  "firstSeenAt": "2025-03-28T08:00:00.000Z",
  "lastSeenAt": "2025-04-02T10:14:00.000Z",
  "firstOpenedAt": "2025-03-28T08:01:12.000Z",
  "lastOpenedAt": "2025-04-02T10:14:00.000Z"
}

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

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

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

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

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

Name	Type	Required	Description
`seenAt`	string	No	ISO timestamp of the seen event (defaults to server time)

{
  "seenAt": "2025-04-02T10:14:00.000Z"
}

SDK Usage

await client.notes.interactions.markSeen("nb_abc123", "node_8f3a2b", {
  seenAt: "2025-04-02T10:14:00.000Z"
});

Response

{
  "nodeId": "node_8f3a2b",
  "collaboratorId": "user_bob",
  "firstSeenAt": "2025-03-28T08:00:00.000Z",
  "lastSeenAt": "2025-04-02T10:14:00.000Z",
  "firstOpenedAt": "2025-03-28T08:01:12.000Z",
  "lastOpenedAt": "2025-04-02T10:14:00.000Z"
}

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

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

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

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

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