Notes: Collaboration

Manage collaborators, reactions, and user roles on notebooks. The collaboration surface is split across three resource families:

• Node collaborators — per-node permissions with roles admin, editor, collaborator, or viewer.
• Node reactions — emoji reactions attached to nodes on behalf of the current user.
• Notebook users — membership in the notebook itself, with roles owner, admin, collaborator, guest, or none.

Note

There are two distinct role enums. The notebook-wide role (on user invites and role changes) is one of owner | admin | collaborator | guest | none. The node-collaborator role is one of admin | editor | collaborator | viewer. Sending "editor" to a notebook-user endpoint returns HTTP 400.

Node 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	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node

cURL

curl -X GET \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/collaborators

SDK

await client.notes.collaborators.list("nb_8f3a2c", "node_4d1e9b")

Response 200

{
  "collaborators": [
    {
      "userId": "user_a1b2c3",
      "role": "admin",
      "name": "Ada Lovelace",
      "username": "ada",
      "avatar": "https://cdn.hoody.icu/u/ada.png",
      "createdAt": "2025-01-12T09:30:00.000Z",
      "updatedAt": "2025-02-04T17:11:42.000Z"
    },
    {
      "userId": "user_d4e5f6",
      "role": "editor",
      "name": "Grace Hopper",
      "username": "grace",
      "avatar": null,
      "createdAt": "2025-01-15T12:00:00.000Z",
      "updatedAt": null
    }
  ]
}

Response 403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "nodeId",
      "message": "Caller is not in the collaborator list for 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

Response 404

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

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	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node

Request Body

Name	Type	Required	Description
collaboratorId	string	Yes	ID of the notebook user to add as a collaborator
role	string	Yes	One of admin, editor, collaborator, viewer

cURL

curl -X POST \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/collaborators \
  -H "Content-Type: application/json" \
  -d '{
    "collaboratorId": "user_d4e5f6",
    "role": "editor"
  }'

SDK

await client.notes.collaborators.add("nb_8f3a2c", "node_4d1e9b", {
  collaboratorId: "user_d4e5f6",
  role: "editor"
})

Response 201

{
  "userId": "user_d4e5f6",
  "role": "editor",
  "createdAt": "2025-03-08T14:22:11.000Z",
  "updatedAt": null
}

Response 400

{
  "message": "Node type does not support collaborators.",
  "code": "bad_request",
  "details": [
    {
      "path": "nodeId",
      "message": "Node type 'text' cannot have 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

Response 403

{
  "message": "You do not have permission to manage collaborators.",
  "code": "forbidden",
  "details": [
    {
      "path": "userId",
      "message": "Caller role 'viewer' cannot add 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

Response 404

{
  "message": "Collaborator user was not found.",
  "code": "user_not_found",
  "details": [
    {
      "path": "collaboratorId",
      "message": "No notebook user with ID user_d4e5f6"
    }
  ]
}

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

Response 409

{
  "message": "Idempotency key conflict.",
  "code": "bad_request",
  "details": [
    {
      "path": "idempotencyKey",
      "message": "Key already used for a different 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

Response 500

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

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node
collaboratorId	path	string	Yes	Identifier of the collaborator to update

Request Body

Name	Type	Required	Description
role	string	Yes	One of admin, editor, collaborator, viewer

cURL

curl -X PATCH \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/collaborators/user_d4e5f6 \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor"
  }'

SDK

await client.notes.collaborators.update("nb_8f3a2c", "node_4d1e9b", "user_d4e5f6", {
  role: "editor"
})

Response 200

{
  "userId": "user_d4e5f6",
  "role": "editor",
  "createdAt": "2025-03-08T14:22:11.000Z",
  "updatedAt": "2025-03-09T08:01:55.000Z"
}

Response 400

{
  "message": "Node type does not support collaborators.",
  "code": "bad_request",
  "details": [
    {
      "path": "nodeId",
      "message": "Node type 'text' cannot have 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

Response 403

{
  "message": "You do not have permission to manage collaborators.",
  "code": "forbidden",
  "details": [
    {
      "path": "userId",
      "message": "Caller role 'viewer' cannot change roles"
    }
  ]
}

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

Response 404

{
  "message": "Collaborator not found.",
  "code": "not_found",
  "details": [
    {
      "path": "collaboratorId",
      "message": "No collaborator with ID user_d4e5f6 on this node"
    }
  ]
}

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

Response 500

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

Removes a collaborator from a node. Requires admin permission.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node
collaboratorId	path	string	Yes	Identifier of the collaborator to remove

cURL

curl -X DELETE \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/collaborators/user_d4e5f6

SDK

await client.notes.collaborators.remove("nb_8f3a2c", "node_4d1e9b", "user_d4e5f6")

Response 200

{
  "success": true
}

Response 400

{
  "message": "Node type does not support collaborators.",
  "code": "bad_request",
  "details": [
    {
      "path": "nodeId",
      "message": "Node type 'text' cannot have 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

Response 403

{
  "message": "You do not have permission to manage collaborators.",
  "code": "forbidden",
  "details": [
    {
      "path": "userId",
      "message": "Caller role 'viewer' cannot remove collaborators"
    }
  ]
}

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

Response 404

{
  "message": "Collaborator not found.",
  "code": "not_found",
  "details": [
    {
      "path": "collaboratorId",
      "message": "No collaborator with ID user_d4e5f6 on this node"
    }
  ]
}

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

Response 500

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

Node reactions

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	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node

cURL

curl -X GET \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/reactions

SDK

await client.notes.reactions.list("nb_8f3a2c", "node_4d1e9b")

Response 200

{
  "reactions": [
    {
      "reaction": "\ud83d\udc4d",
      "collaboratorId": "user_a1b2c3",
      "createdAt": "2025-03-08T14:22:11.000Z",
      "name": "Ada Lovelace",
      "username": "ada"
    },
    {
      "reaction": "\ud83c\udf89",
      "collaboratorId": "user_d4e5f6",
      "createdAt": "2025-03-09T10:05:00.000Z",
      "name": "Grace Hopper",
      "username": "grace"
    }
  ]
}

Response 403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "nodeId",
      "message": "Caller is not in the collaborator list for 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

Response 404

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

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	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node

Request Body

Name	Type	Required	Description
reaction	string	Yes	The reaction string (1 to 64 characters)

cURL

curl -X POST \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/reactions \
  -H "Content-Type: application/json" \
  -d '{
    "reaction": "\ud83d\udc4d"
  }'

SDK

await client.notes.reactions.add("nb_8f3a2c", "node_4d1e9b", {
  reaction: "\ud83d\udc4d"
})

Response 201

{
  "reaction": "\ud83d\udc4d",
  "collaboratorId": "user_a1b2c3",
  "createdAt": "2025-03-08T14:22:11.000Z"
}

Response 400

{
  "message": "Invalid reaction payload.",
  "code": "bad_request",
  "details": [
    {
      "path": "reaction",
      "message": "Field must be between 1 and 64 characters"
    }
  ]
}

Response 403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "nodeId",
      "message": "Caller is not in the collaborator list for 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

Response 404

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

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

Response 409

{
  "message": "Idempotency key conflict.",
  "code": "bad_request",
  "details": [
    {
      "path": "idempotencyKey",
      "message": "Key already used for a different 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

Response 500

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

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook
nodeId	path	string	Yes	Identifier of the node
reaction	path	string	Yes	The reaction string to remove

cURL

curl -X DELETE \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/nodes/node_4d1e9b/reactions/%F0%9F%91%8D

SDK

await client.notes.reactions.remove("nb_8f3a2c", "node_4d1e9b", "\ud83d\udc4d")

Response 200

{
  "success": true
}

Response 403

{
  "message": "You do not have access to this node.",
  "code": "forbidden",
  "details": [
    {
      "path": "nodeId",
      "message": "Caller is not in the collaborator list for 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

Response 404

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

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

Response 500

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

Notebook users

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

Creates one or more users in the notebook by username. Returns created users and any per-entry errors.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook

Request Body

Name	Type	Required	Description
users	array	Yes	Up to 50 user entries to invite

Each entry in users has the following shape:

Name	Type	Required	Description
username	string	Yes	Username to add to the notebook
role	string	Yes	One of owner, admin, collaborator, guest, none

cURL

curl -X POST \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/users \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "username": "grace",
        "role": "admin"
      },
      {
        "username": "linus",
        "role": "collaborator"
      }
    ]
  }'

SDK

await client.notes.users.invite("nb_8f3a2c", {
  users: [
    { username: "grace", role: "admin" },
    { username: "linus", role: "collaborator" }
  ]
})

Response 200

{
  "users": [
    {
      "id": "user_d4e5f6",
      "name": "Grace Hopper",
      "avatar": "https://cdn.hoody.icu/u/grace.png",
      "role": "admin",
      "customName": null,
      "customAvatar": null,
      "createdAt": "2025-03-08T14:22:11.000Z",
      "updatedAt": null,
      "revision": "rev_01HXY2A4C8",
      "status": 1
    },
    {
      "id": "user_g7h8i9",
      "name": "Linus Torvalds",
      "avatar": null,
      "role": "collaborator",
      "customName": null,
      "customAvatar": null,
      "createdAt": "2025-03-08T14:22:11.000Z",
      "updatedAt": null,
      "revision": "rev_01HXY2A4C9",
      "status": 2
    }
  ],
  "errors": []
}

Response 400

{
  "message": "At least one user is required.",
  "code": "user_input_required",
  "details": [
    {
      "path": "users",
      "message": "Field must contain at least one entry"
    }
  ]
}

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

Response 403

{
  "message": "You do not have permission to add users.",
  "code": "user_invite_no_access",
  "details": [
    {
      "path": "userId",
      "message": "Caller role 'guest' cannot invite"
    }
  ]
}

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

Response 404

{
  "message": "Notebook not found.",
  "code": "not_found",
  "details": [
    {
      "path": "notebookId",
      "message": "No notebook with ID nb_8f3a2c"
    }
  ]
}

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

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

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	Identifier of the notebook
userId	path	string	Yes	Identifier of the user whose role is being changed

Request Body

Name	Type	Required	Description
role	string	Yes	One of owner, admin, collaborator, guest, none

cURL

curl -X PATCH \
  https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a2c/users/user_g7h8i9/role \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

SDK

await client.notes.users.updateRole("nb_8f3a2c", "user_g7h8i9", {
  role: "admin"
})

Response 200

{
  "id": "user_g7h8i9",
  "name": "Linus Torvalds",
  "avatar": null,
  "role": "admin",
  "customName": null,
  "customAvatar": null,
  "createdAt": "2025-03-08T14:22:11.000Z",
  "updatedAt": "2025-03-09T08:01:55.000Z",
  "revision": "rev_01HXY2B7D1",
  "status": 1
}

Response 400

{
  "message": "Invalid role value.",
  "code": "bad_request",
  "details": [
    {
      "path": "role",
      "message": "Value must be one of owner, admin, collaborator, guest, none"
    }
  ]
}

Response 403

{
  "message": "You do not have permission to update user roles.",
  "code": "user_update_no_access",
  "details": [
    {
      "path": "userId",
      "message": "Caller role 'collaborator' cannot change 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

Response 404

{
  "message": "User not found.",
  "code": "user_not_found",
  "details": [
    {
      "path": "userId",
      "message": "No user with ID user_g7h8i9 in this notebook"
    }
  ]
}

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