Notes: Collaboration

The Notes Collaboration APIs control who can access a notebook, what role they hold, and how users interact with content. Use these endpoints to invite users to a notebook and assign notebook-wide roles, attach per-node collaborators with finer-grained roles on sections, pages, and databases, and add or remove emoji reactions on individual nodes.

Node collaborators

Manage per-node collaborator membership and roles. Each collaborator has a role scoped to a single node (section, page, or database). The valid node-scoped roles are admin, editor, collaborator, and viewer. Only node admins may add, update, or remove collaborators.

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

Returns all collaborators on a node with their roles and user info.

Parameters

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

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/collaborators" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const collaborators = await client.notes.collaborators.list('notebookId', 'nodeId');

{
  "collaborators": [
    {
      "userId": "a1b2c3d4e5f678901234abcd",
      "role": "editor",
      "name": "Ada Lovelace",
      "username": "ada",
      "avatar": "https://avatars.example.com/ada.png",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-02-01T08:12:00.000Z"
    },
    {
      "userId": "b2c3d4e5f678901234abcd0",
      "role": "viewer",
      "name": "Grace Hopper",
      "username": "grace",
      "avatar": null,
      "createdAt": "2026-01-16T14:05:00.000Z",
      "updatedAt": null
    }
  ]
}

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

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

{
  "code": "not_found",
  "message": "Node 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/{nodeId}/collaborators`

Adds a user as a collaborator on a node with a specified role. Requires admin permission.

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
`collaboratorId`	string	Yes	The user ID of the collaborator to add
`role`	string	Yes	Node-scoped role. One of: `admin`, `editor`, `collaborator`, `viewer`

curl -X POST "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/collaborators" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "collaboratorId": "a1b2c3d4e5f678901234abcd",
    "role": "editor"
  }'

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.notes.collaborators.add('notebookId', 'nodeId', {
  collaboratorId: 'a1b2c3d4e5f678901234abcd',
  role: 'editor'
});

{
  "userId": "a1b2c3d4e5f678901234abcd",
  "role": "editor",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

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

Error Code	Title	Description	Resolution
`bad_request`	Unsupported node type	This node type does not support collaborators	Collaborators can only be added to sections, pages, and databases

{
  "code": "forbidden",
  "message": "You do not have permission to manage collaborators."
}

Error Code	Title	Description	Resolution
`forbidden`	Not an admin	Only admins can manage collaborators on this node	Request admin access from the node owner

{
  "code": "user_not_found",
  "message": "Collaborator user was not found."
}

Error Code	Title	Description	Resolution
`user_not_found`	User not found	The collaborator user does not exist in this notebook	Verify user ID or create the user with createUsers first

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

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

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

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}/collaborators/{collaboratorId}`

Changes the role of an existing collaborator. Requires admin permission.

Parameters

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

Request Body

Field	Type	Required	Description
`role`	string	Yes	The new node-scoped role. One of: `admin`, `editor`, `collaborator`, `viewer`

curl -X PATCH "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/collaborators/{collaboratorId}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "role": "editor" }'

import { HoodyClient } from 'hoody-sdk';

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

const updated = await client.notes.collaborators.update('notebookId', 'nodeId', 'collaboratorId', {
  role: 'editor'
});

{
  "userId": "a1b2c3d4e5f678901234abcd",
  "role": "editor",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-02-02T09:00:00.000Z"
}

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

Error Code	Title	Description	Resolution
`bad_request`	Unsupported node type	This node type does not support collaborators	Collaborators can only be managed on sections, pages, and databases

{
  "code": "forbidden",
  "message": "You do not have permission to manage collaborators."
}

Error Code	Title	Description	Resolution
`forbidden`	Not an admin	Only admins can change collaborator roles	Request admin access from the node owner

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

Error Code	Title	Description	Resolution
`not_found`	Collaborator not found	No collaborator with the given ID exists on this node	Verify collaborator ID using listCollaborators

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

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}/collaborators/{collaboratorId}`

Removes a collaborator from a node. Requires admin permission.

Parameters

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

curl -X DELETE "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/collaborators/{collaboratorId}" \
  -H "Authorization: Bearer <token>"

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.collaborators.remove('notebookId', 'nodeId', 'collaboratorId');

{
  "success": true
}

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

Error Code	Title	Description	Resolution
`bad_request`	Unsupported node type	This node type does not support collaborators	Collaborators can only be managed on sections, pages, and databases

{
  "code": "forbidden",
  "message": "You do not have permission to manage collaborators."
}

Error Code	Title	Description	Resolution
`forbidden`	Not an admin	Only admins can remove collaborators	Request admin access from the node owner

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

Error Code	Title	Description	Resolution
`not_found`	Collaborator not found	No collaborator with the given ID exists on this node	Verify collaborator ID using listCollaborators

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

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

Node reactions

Add or remove emoji reactions on individual notebook nodes. Reactions are scoped to a single node and attributed to the collaborator who reacted.

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

Returns all reactions on a node with the collaborator who reacted.

Parameters

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

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/reactions" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const reactions = await client.notes.reactions.list('notebookId', 'nodeId');

{
  "reactions": [
    {
      "reaction": "\uD83D\uDE00",
      "collaboratorId": "a1b2c3d4e5f678901234abcd",
      "createdAt": "2026-01-15T10:30:00.000Z",
      "name": "Ada Lovelace",
      "username": "ada"
    },
    {
      "reaction": "\uD83C\uDF89",
      "collaboratorId": "b2c3d4e5f678901234abcd0",
      "createdAt": "2026-01-16T11:42:00.000Z",
      "name": "Grace Hopper",
      "username": "grace"
    }
  ]
}

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

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

{
  "code": "not_found",
  "message": "Node 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/{nodeId}/reactions`

Adds an emoji reaction to a node on behalf of the current user.

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
`reaction`	string	Yes	The reaction string, between 1 and 64 characters

curl -X POST "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/reactions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reaction": "\uD83D\uDE00" }'

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.notes.reactions.add('notebookId', 'nodeId', {
  reaction: '\uD83D\uDE00'
});

{
  "reaction": "\uD83D\uDE00",
  "collaboratorId": "a1b2c3d4e5f678901234abcd",
  "createdAt": "2026-01-15T10:30:00.000Z"
}

{
  "code": "<error-code>",
  "message": "<error-message>",
  "details": []
}

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

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

{
  "code": "not_found",
  "message": "Node 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

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

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

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

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}/reactions/{reaction}`

Removes an emoji reaction from a node for the current user.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook identifier
`nodeId`	path	string	Yes	The node identifier
`reaction`	path	string	Yes	The reaction string to remove (URL-encoded)

curl -X DELETE "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/reactions/%F0%9F%98%80" \
  -H "Authorization: Bearer <token>"

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.reactions.remove('notebookId', 'nodeId', '\uD83D\uDE00');

{
  "success": true
}

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

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

{
  "code": "not_found",
  "message": "Node 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

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

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

Notebook users

Invite users to a notebook and manage their notebook-wide role. These endpoints operate on the notebook as a whole and are distinct from the per-node collaborator endpoints above.

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

Creates one or more users in the notebook by username. Returns the created users along with any per-user errors. Up to 50 users may be invited per request.

Parameters

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

Request Body

Field	Type	Required	Description
`users`	array	Yes	List of users to invite, maximum 50 entries

Each entry in users has the following fields:

Field	Type	Required	Description
`username`	string	Yes	The username to invite
`role`	string	Yes	Notebook-wide role. One of: `owner`, `admin`, `collaborator`, `guest`, `none`

curl -X POST "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/users" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "username": "ada", "role": "collaborator" },
      { "username": "grace", "role": "admin" }
    ]
  }'

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.notes.users.invite('notebookId', {
  users: [
    { username: 'ada', role: 'collaborator' },
    { username: 'grace', role: 'admin' }
  ]
});

{
  "users": [
    {
      "id": "a1b2c3d4e5f678901234abcd",
      "name": "ada",
      "avatar": null,
      "role": "collaborator",
      "customName": null,
      "customAvatar": null,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": null,
      "revision": "01HABCDEFGHIJKLMNOPQRST",
      "status": 1
    },
    {
      "id": "b2c3d4e5f678901234abcd0",
      "name": "grace",
      "avatar": null,
      "role": "admin",
      "customName": null,
      "customAvatar": null,
      "createdAt": "2026-01-15T10:31:00.000Z",
      "updatedAt": null,
      "revision": "01HABCDEFGHIJKLMNOPQRST",
      "status": 1
    }
  ],
  "errors": []
}

{
  "code": "user_input_required",
  "message": "At least one user is required."
}

Error Code	Title	Description	Resolution
`user_input_required`	User input required	At least one user must be provided in the request body	Provide a non-empty users array with username and role

{
  "code": "user_invite_no_access",
  "message": "You do not have permission to add users."
}

Error Code	Title	Description	Resolution
`notebook_readonly`	Notebook is read-only	The notebook is in read-only mode and cannot be modified	Contact the notebook owner to restore write access
`user_invite_no_access`	No permission to add users	User role does not have permission to add users to this notebook	Only owners and admins can add users

{
  "code": "<error-code>",
  "message": "<error-message>",
  "details": []
}

`PATCH /api/v1/notes/notebooks/{notebookId}/users/{userId}/role`

Changes the notebook-wide role of a user. Requires owner or admin permission.

Parameters

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

Request Body

Field	Type	Required	Description
`role`	string	Yes	The new notebook-wide role. One of: `owner`, `admin`, `collaborator`, `guest`, `none`

curl -X PATCH "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/{notebookId}/users/{userId}/role" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

import { HoodyClient } from 'hoody-sdk';

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

const updated = await client.notes.users.updateRole('notebookId', 'userId', {
  role: 'admin'
});

{
  "id": "a1b2c3d4e5f678901234abcd",
  "name": "ada",
  "avatar": null,
  "role": "admin",
  "customName": null,
  "customAvatar": null,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-16T08:00:00.000Z",
  "revision": "01HABCDEFGHIJKLMNOPQRST",
  "status": 1
}

{
  "code": "<error-code>",
  "message": "<error-message>",
  "details": []
}

{
  "code": "user_update_no_access",
  "message": "You do not have permission to update user roles."
}

Error Code	Title	Description	Resolution
`notebook_readonly`	Notebook is read-only	The notebook is in read-only mode and cannot be modified	Contact the notebook owner to restore write access
`user_update_no_access`	No permission to update users	User role does not have permission to change user roles	Only owners and admins can change user roles

{
  "code": "user_not_found",
  "message": "User not found."
}

Error Code	Title	Description	Resolution
`user_not_found`	User not found	No user exists with the provided ID in this notebook	Verify user ID using the users list