The Notes Notebooks API lets you create, retrieve, update, and delete notebooks. Use these endpoints to manage the top-level containers that hold your notes, files, and collaborative content. Notebook ownership and role permissions govern which operations a given user can perform.

Notebook Object

A notebook represents the top-level container in the Notes service. Key fields include:

Field	Type	Required	Description
id	string	Yes	Unique identifier of the notebook
name	string	Yes	Display name of the notebook
description	string | null	No	Optional description
avatar	string | null	No	Optional avatar URL or identifier
user	object	Yes	Object containing the requesting user’s id and role within the notebook
user.role	string	Yes	One of owner, admin, collaborator, guest, none
status	number	Yes	Notebook status code (1, 2, or 3)
maxFileSize	string	No	Maximum allowed file size for uploads to this notebook

---

GET /api/v1/notes/notebooks

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

SDK

await client.notes.notebooks.listNotebooks();

cURL

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

Response

200

{
  "notebooks": [
    {
      "id": "nb_8f3a2b1c4d5e6f7g",
      "name": "Product Roadmap",
      "description": "Q4 planning and roadmap tracking",
      "avatar": null,
      "user": {
        "id": "usr_1a2b3c4d5e6f7g8h",
        "role": "owner"
      },
      "status": 1,
      "maxFileSize": "104857600"
    },
    {
      "id": "nb_9h8g7f6e5d4c3b2a",
      "name": "Engineering Wiki",
      "description": null,
      "avatar": "https://cdn.hoody.com/avatars/eng-wiki.png",
      "user": {
        "id": "usr_1a2b3c4d5e6f7g8h",
        "role": "collaborator"
      },
      "status": 1,
      "maxFileSize": "52428800"
    }
  ]
}

400

{
  "code": "bad_request",
  "message": "Bad request.",
  "details": [
    {
      "path": "limit",
      "message": "Must be a positive integer"
    }
  ]
}

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

403

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

---

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

Retrieve metadata for a single notebook, including the current user’s role within it.

Parameters

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

SDK

await client.notes.notebooks.get("nb_8f3a2b1c4d5e6f7g");

cURL

curl -X GET https://api.hoody.com/api/v1/notes/notebooks/nb_8f3a2b1c4d5e6f7g \
  -H "Authorization: Bearer <token>"

Response

200

{
  "id": "nb_8f3a2b1c4d5e6f7g",
  "name": "Product Roadmap",
  "description": "Q4 planning and roadmap tracking",
  "avatar": null,
  "user": {
    "id": "usr_1a2b3c4d5e6f7g8h",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "104857600"
}

400

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

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

403

{
  "code": "notebook_no_access",
  "message": "You do not have access to this notebook.",
  "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

404

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

---

POST /api/v1/notes/notebooks

Create a new notebook. The calling user becomes the owner.

Request Body

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

SDK

await client.notes.notebooks.create({
  name: "Product Roadmap",
  description: "Q4 planning and roadmap tracking",
  avatar: null
});

cURL

curl -X POST https://api.hoody.com/api/v1/notes/notebooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Roadmap",
    "description": "Q4 planning and roadmap tracking",
    "avatar": null
  }'

Response

200

{
  "id": "nb_8f3a2b1c4d5e6f7g",
  "name": "Product Roadmap",
  "description": "Q4 planning and roadmap tracking",
  "avatar": null,
  "user": {
    "id": "usr_1a2b3c4d5e6f7g8h",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "104857600"
}

400

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

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

---

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

Update a notebook’s 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	New display name for the notebook
description	string | null	No	New description for the notebook
avatar	string | null	No	New avatar URL or identifier

SDK

await client.notes.notebooks.update("nb_8f3a2b1c4d5e6f7g", {
  name: "Product Roadmap 2025",
  description: "Updated Q1 planning workspace",
  avatar: null
});

cURL

curl -X PATCH https://api.hoody.com/api/v1/notes/notebooks/nb_8f3a2b1c4d5e6f7g \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Roadmap 2025",
    "description": "Updated Q1 planning workspace",
    "avatar": null
  }'

Response

200

{
  "id": "nb_8f3a2b1c4d5e6f7g",
  "name": "Product Roadmap 2025",
  "description": "Updated Q1 planning workspace",
  "avatar": null,
  "user": {
    "id": "usr_1a2b3c4d5e6f7g8h",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "104857600"
}

400

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

403

{
  "code": "notebook_update_not_allowed",
  "message": "You do not have permission to update this notebook.",
  "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

404

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

500

{
  "code": "notebook_update_failed",
  "message": "Failed to update notebook.",
  "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

Caution

Deleting a notebook permanently removes all its contents. This action cannot be undone.

---

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

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

Parameters

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

SDK

await client.notes.notebooks.delete("nb_8f3a2b1c4d5e6f7g");

cURL

curl -X DELETE https://api.hoody.com/api/v1/notes/notebooks/nb_8f3a2b1c4d5e6f7g \
  -H "Authorization: Bearer <token>"

Response

200

{
  "id": "nb_8f3a2b1c4d5e6f7g",
  "name": "Product Roadmap",
  "description": "Q4 planning and roadmap tracking",
  "avatar": null,
  "user": {
    "id": "usr_1a2b3c4d5e6f7g8h",
    "role": "owner"
  },
  "status": 3,
  "maxFileSize": "104857600"
}

400

{
  "code": "bad_request",
  "message": "Invalid notebook ID.",
  "details": [
    {
      "path": "notebookId",
      "message": "Must be a valid identifier"
    }
  ]
}

403

{
  "code": "notebook_delete_not_allowed",
  "message": "You do not have permission to delete this notebook.",
  "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

404

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