Notes: Notebooks

Create, retrieve, update, and delete notebooks. A notebook is the top-level container for collaborative notes within a project. Notebooks have members with roles such as owner, admin, collaborator, guest, and none. Only owners can update or delete a notebook.

The notebook object exposes an id, name, optional description and avatar, the calling user’s role inside the notebook, a numeric status, and the maximum allowed file size (maxFileSize).

List notebooks

GET /api/v1/notes/notebooks

Returns all notebooks the requesting user is a member of. Notebooks where the user has role none and notebooks with inactive status are excluded.

This endpoint takes no parameters.

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks" \
  -H "Authorization: Bearer &lt;token&gt;"

const { notebooks } = await client.notes.notebooks.listNotebooks();

{
  "notebooks": [
    {
      "id": "nb_8f3a1c9e2b0d4f7a",
      "name": "Engineering wiki",
      "description": "Shared engineering notes and runbooks",
      "avatar": null,
      "user": {
        "id": "usr_4b2c1d8e9f0a3b5c",
        "role": "owner"
      },
      "status": 1,
      "maxFileSize": "10485760"
    },
    {
      "id": "nb_2a7c5e9f1b3d8a40",
      "name": "Design reviews",
      "description": null,
      "avatar": "https://cdn.hoody.icu/avatars/nb_2a7c5e9f1b3d8a40.png",
      "user": {
        "id": "usr_4b2c1d8e9f0a3b5c",
        "role": "collaborator"
      },
      "status": 1,
      "maxFileSize": "10485760"
    }
  ]
}

{
  "message": "Bad request.",
  "code": "bad_request",
  "details": []
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	Invalid query parameters	Verify request format and identity parameters

{
  "message": "You are not allowed to list notebooks.",
  "code": "forbidden",
  "details": []
}

Get notebook details

GET /api/v1/notes/notebooks/{notebookId}

Returns notebook metadata including name, description, avatar, status, and the current user’s role.

Parameters

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

curl -X GET "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a1c9e2b0d4f7a" \
  -H "Authorization: Bearer &lt;token&gt;"

const notebook = await client.notes.notebooks.get("nb_8f3a1c9e2b0d4f7a");

{
  "id": "nb_8f3a1c9e2b0d4f7a",
  "name": "Engineering wiki",
  "description": "Shared engineering notes and runbooks",
  "avatar": null,
  "user": {
    "id": "usr_4b2c1d8e9f0a3b5c",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10485760"
}

{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": [
    {
      "path": "notebookId",
      "message": "Notebook not found."
    }
  ]
}

Error Code	Title	Description	Resolution
`notebook_not_found`	Notebook not found	No notebook exists for the current user context	Verify the notebook ID in the URL and user identity params

{
  "message": "You do not have access to this notebook.",
  "code": "notebook_no_access",
  "details": []
}

Error Code	Title	Description	Resolution
`notebook_no_access`	No access to notebook	User does not have access to this notebook	Verify user identity or request access from the owner

{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": []
}

Create a notebook

POST /api/v1/notes/notebooks

Creates a new notebook with the given name, description, and avatar. The calling user is assigned the owner role for the new notebook.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name of the notebook
`description`	string \| null	No	Optional description of the notebook
`avatar`	string \| null	No	Optional URL or identifier for the notebook avatar

This endpoint takes no path, query, or header parameters.

curl -X POST "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product roadmap",
    "description": "Quarterly roadmap and planning notes",
    "avatar": null
  }'

const notebook = await client.notes.notebooks.create({
  name: "Product roadmap",
  description: "Quarterly roadmap and planning notes",
  avatar: null,
});

{
  "id": "nb_9d4e2f1a8b6c3705",
  "name": "Product roadmap",
  "description": "Quarterly roadmap and planning notes",
  "avatar": null,
  "user": {
    "id": "usr_4b2c1d8e9f0a3b5c",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10485760"
}

{
  "message": "Notebook name is required.",
  "code": "notebook_name_required",
  "details": [
    {
      "path": "name",
      "message": "Notebook name is required."
    }
  ]
}

Error Code	Title	Description	Resolution
`notebook_name_required`	Name required	Notebook name is required and cannot be empty	Provide a non-empty name in the request body

Update notebook settings

PATCH /api/v1/notes/notebooks/{notebookId}

Updates notebook name, description, or avatar. Only notebook owners can update.

Parameters

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

Request Body

Field	Type	Required	Description
`name`	string	Yes	Updated display name of the notebook
`description`	string \| null	No	Updated description of the notebook
`avatar`	string \| null	No	Updated URL or identifier for the notebook avatar

curl -X PATCH "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a1c9e2b0d4f7a" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering wiki (v2)",
    "description": "Shared engineering notes and runbooks",
    "avatar": "https://cdn.hoody.icu/avatars/nb_8f3a1c9e2b0d4f7a.png"
  }'

const notebook = await client.notes.notebooks.update("nb_8f3a1c9e2b0d4f7a", {
  name: "Engineering wiki (v2)",
  description: "Shared engineering notes and runbooks",
  avatar: "https://cdn.hoody.icu/avatars/nb_8f3a1c9e2b0d4f7a.png",
});

{
  "id": "nb_8f3a1c9e2b0d4f7a",
  "name": "Engineering wiki (v2)",
  "description": "Shared engineering notes and runbooks",
  "avatar": "https://cdn.hoody.icu/avatars/nb_8f3a1c9e2b0d4f7a.png",
  "user": {
    "id": "usr_4b2c1d8e9f0a3b5c",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10485760"
}

{
  "message": "Invalid request body.",
  "code": "bad_request",
  "details": [
    {
      "path": "name",
      "message": "Name must be a non-empty string."
    }
  ]
}

{
  "message": "Notebook is read-only.",
  "code": "notebook_readonly",
  "details": []
}

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
`notebook_update_not_allowed`	Update not allowed	User role does not have permission to update this notebook	Only owners and admins can update notebook settings

{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": []
}

{
  "message": "Failed to update notebook.",
  "code": "notebook_update_failed",
  "details": []
}

Error Code	Title	Description	Resolution
`notebook_update_failed`	Update failed	Notebook update failed due to a server error	Retry the request; if it persists, contact support

Delete a notebook

DELETE /api/v1/notes/notebooks/{notebookId}

Permanently deletes a notebook and all its data. Only notebook owners can delete.

Parameters

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

curl -X DELETE "https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.icu/api/v1/notes/notebooks/nb_8f3a1c9e2b0d4f7a" \
  -H "Authorization: Bearer &lt;token&gt;"

const deleted = await client.notes.notebooks.delete("nb_8f3a1c9e2b0d4f7a");

{
  "id": "nb_8f3a1c9e2b0d4f7a",
  "name": "Engineering wiki",
  "description": "Shared engineering notes and runbooks",
  "avatar": null,
  "user": {
    "id": "usr_4b2c1d8e9f0a3b5c",
    "role": "owner"
  },
  "status": 3,
  "maxFileSize": "10485760"
}

{
  "message": "Invalid notebook ID.",
  "code": "bad_request",
  "details": [
    {
      "path": "notebookId",
      "message": "Notebook ID is invalid."
    }
  ]
}

{
  "message": "You do not have permission to delete this notebook.",
  "code": "notebook_delete_not_allowed",
  "details": []
}

Error Code	Title	Description	Resolution
`notebook_delete_not_allowed`	Delete not allowed	Only the notebook owner can delete the notebook	Request the owner to delete the notebook

{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": []
}

Error Code	Title	Description	Resolution
`notebook_not_found`	Notebook not found	No notebook exists with the provided ID	Verify the notebook ID in the URL