Notes: Collaboration

Manage collaborators, emoji reactions, and notebook-wide user roles. Use these endpoints to control who can access a node, who can react to a node, and which users belong to a notebook.

Node collaborators

Manage user access on a specific node (section, page, or database) within a notebook. Node-scoped roles use the admin | editor | collaborator | viewer enum.

`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 containing the node
`nodeId`	path	string	Yes	Identifier of the node whose collaborators are being listed

This endpoint takes no request body.

curl -X GET "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/collaborators" \
  -H "Authorization: Bearer <token>"

const { collaborators } = await client.notes.collaborators.list({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
});

Response

{
  "collaborators": [
    {
      "userId": "3c2b1a0d9e8f7654abcdef12",
      "role": "editor",
      "name": "Alice Johnson",
      "username": "alice",
      "avatar": "https://cdn.hoody.com/avatars/alice.png",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": null
    },
    {
      "userId": "9f8e7d6c5b4a3210fedcba98",
      "role": "viewer",
      "name": "Bob Smith",
      "username": "bob",
      "avatar": null,
      "createdAt": "2024-01-16T08:15:00.000Z",
      "updatedAt": "2024-01-17T12:00:00.000Z"
    }
  ]
}

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

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

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

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 containing the node
`nodeId`	path	string	Yes	Identifier of the node on which to add the collaborator

Request body

Name	Type	Required	Description
`collaboratorId`	string	Yes	ID of the user to add as a collaborator
`role`	string	Yes	Node-scoped role. One of: `admin`, `editor`, `collaborator`, `viewer`

Example request

cURL
SDK

curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/collaborators" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "collaboratorId": "3c2b1a0d9e8f7654abcdef12",
    "role": "editor"
  }'

const collaborator = await client.notes.collaborators.add({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
  data: {
    collaboratorId: "3c2b1a0d9e8f7654abcdef12",
    role: "editor",
  },
});

Response

{
  "userId": "3c2b1a0d9e8f7654abcdef12",
  "role": "editor",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": null
}

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

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

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

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

{
  "message": "Collaborator user was not found.",
  "code": "user_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

{
  "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}/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 containing the node
`nodeId`	path	string	Yes	Identifier of the node whose collaborator is being updated
`collaboratorId`	path	string	Yes	ID of the collaborator whose role should change

Request body

Name	Type	Required	Description
`role`	string	Yes	New node-scoped role. One of: `admin`, `editor`, `collaborator`, `viewer`

Example request

cURL
SDK

curl -X PATCH "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/collaborators/3c2b1a0d9e8f7654abcdef12" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer"
  }'

const updated = await client.notes.collaborators.update({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
  collaboratorId: "3c2b1a0d9e8f7654abcdef12",
  data: {
    role: "viewer",
  },
});

Response

{
  "userId": "3c2b1a0d9e8f7654abcdef12",
  "role": "viewer",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-18T14:22:00.000Z"
}

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

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

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

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

{
  "message": "Collaborator not found.",
  "code": "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

{
  "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}/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 containing the node
`nodeId`	path	string	Yes	Identifier of the node from which to remove the collaborator
`collaboratorId`	path	string	Yes	ID of the collaborator to remove

This endpoint takes no request body.

Example request

cURL
SDK

curl -X DELETE "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/collaborators/3c2b1a0d9e8f7654abcdef12" \
  -H "Authorization: Bearer <token>"

await client.notes.collaborators.remove({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
  collaboratorId: "3c2b1a0d9e8f7654abcdef12",
});

Response

{
  "success": true
}

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

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

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

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

{
  "message": "Collaborator not found.",
  "code": "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

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

Node reactions

Manage emoji reactions on nodes. The reaction value is an emoji string of 1–64 characters.

`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 containing the node
`nodeId`	path	string	Yes	Identifier of the node whose reactions are being listed

This endpoint takes no request body.

Example request

cURL
SDK

curl -X GET "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/reactions" \
  -H "Authorization: Bearer <token>"

const { reactions } = await client.notes.reactions.list({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
});

Response

{
  "reactions": [
    {
      "reaction": "🎉",
      "collaboratorId": "3c2b1a0d9e8f7654abcdef12",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "name": "Alice Johnson",
      "username": "alice"
    },
    {
      "reaction": "👍",
      "collaboratorId": "9f8e7d6c5b4a3210fedcba98",
      "createdAt": "2024-01-15T11:05:00.000Z",
      "name": "Bob Smith",
      "username": "bob"
    }
  ]
}

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

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

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

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 containing the node
`nodeId`	path	string	Yes	Identifier of the node to react to

Request body

Name	Type	Required	Description
`reaction`	string	Yes	Emoji reaction string, between 1 and 64 characters

Example request

cURL
SDK

curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/reactions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reaction": "🎉"
  }'

const reaction = await client.notes.reactions.add({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
  data: {
    reaction: "🎉",
  },
});

Response

{
  "reaction": "🎉",
  "collaboratorId": "3c2b1a0d9e8f7654abcdef12",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

{
  "message": "Invalid reaction payload.",
  "code": "bad_request",
  "details": [
    {
      "path": "reaction",
      "message": "Must be a non-empty string up to 64 characters"
    }
  ]
}

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

`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 containing the node
`nodeId`	path	string	Yes	Identifier of the node whose reaction should be removed
`reaction`	path	string	Yes	Emoji reaction string to remove

This endpoint takes no request body.

Example request

cURL
SDK

curl -X DELETE "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/nodes/5a4b3c2d1e0f6789abcdef12/reactions/%F0%9F%8E%89" \
  -H "Authorization: Bearer <token>"

await client.notes.reactions.remove({
  notebookId: "nb_8f7d6e5c4b3a2910",
  nodeId: "5a4b3c2d1e0f6789abcdef12",
  reaction: "🎉",
});

Response

{
  "success": true
}

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

Notebook users

Manage users and their notebook-wide role. Roles here use the owner | admin | collaborator | guest | none enum.

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

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

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Identifier of the notebook to invite users into

Request body

Name	Type	Required	Description
`users`	array	Yes	List of users to invite. Maximum 50 entries. Each entry requires `username` and `role`.
`users[].username`	string	Yes	Username of the user to invite
`users[].role`	string	Yes	Notebook-wide role. One of: `owner`, `admin`, `collaborator`, `guest`, `none`

Example request

cURL
SDK

curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/users" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      { "username": "alice", "role": "collaborator" },
      { "username": "bob", "role": "admin" }
    ]
  }'

const { users, errors } = await client.notes.users.invite({
  notebookId: "nb_8f7d6e5c4b3a2910",
  data: {
    users: [
      { username: "alice", role: "collaborator" },
      { username: "bob", role: "admin" },
    ],
  },
});

Response

{
  "users": [
    {
      "id": "3c2b1a0d9e8f7654abcdef12",
      "name": "Alice Johnson",
      "avatar": "https://cdn.hoody.com/avatars/alice.png",
      "role": "collaborator",
      "customName": null,
      "customAvatar": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": null,
      "revision": "rev_8a7b6c5d4e3f",
      "status": 1
    },
    {
      "id": "9f8e7d6c5b4a3210fedcba98",
      "name": "Bob Smith",
      "avatar": null,
      "role": "admin",
      "customName": "Robert",
      "customAvatar": null,
      "createdAt": "2024-01-15T10:30:01.000Z",
      "updatedAt": null,
      "revision": "rev_1b2c3d4e5f6a",
      "status": 2
    }
  ],
  "errors": [
    {
      "username": "nonexistent_user",
      "error": "Username not found"
    }
  ]
}

{
  "message": "At least one user is required.",
  "code": "user_input_required",
  "details": [
    {
      "path": "users",
      "message": "Array 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

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

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

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

`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 containing the user
`userId`	path	string	Yes	Identifier of the user whose role should change

Request body

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

Example request

cURL
SDK

curl -X PATCH "https://api.hoody.com/api/v1/notes/notebooks/nb_8f7d6e5c4b3a2910/users/3c2b1a0d9e8f7654abcdef12/role" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'

const user = await client.notes.users.updateRole({
  notebookId: "nb_8f7d6e5c4b3a2910",
  userId: "3c2b1a0d9e8f7654abcdef12",
  data: {
    role: "admin",
  },
});

Response

{
  "id": "3c2b1a0d9e8f7654abcdef12",
  "name": "Alice Johnson",
  "avatar": "https://cdn.hoody.com/avatars/alice.png",
  "role": "admin",
  "customName": null,
  "customAvatar": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-18T14:22:00.000Z",
  "revision": "rev_2c3d4e5f6a7b",
  "status": 1
}

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

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

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

{
  "message": "User not found.",
  "code": "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