Notes: Notebooks

Notebooks are the top-level containers in the Notes service. Each notebook groups related notes and files, has its own membership list with role-based permissions, and exposes metadata through the REST endpoints documented below. Use these endpoints to list the notebooks you have access to, fetch a single notebook’s details, create new notebooks, update notebook settings, or permanently delete a notebook you own.

Notebook membership is governed by roles: owner, admin, collaborator, guest, and none. Notebooks where the caller has role none are filtered out of list responses, and write operations (update, delete) are restricted to the owner.

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 from the response.

This endpoint takes no parameters.

cURL

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

TypeScript SDK

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.notebooks.listNotebooks();

200

{
  "notebooks": [
    {
      "id": "nb_64f8a2b1c3d4e5f6a7b8c9d0",
      "name": "Engineering Wiki",
      "description": "Shared documentation for the engineering team.",
      "avatar": "https://cdn.example.com/avatars/eng-wiki.png",
      "user": {
        "id": "usr_5f9b3c4d8e2a1f0b6c7d8e9f",
        "role": "owner"
      },
      "status": 1,
      "maxFileSize": "50MB"
    },
    {
      "id": "nb_78ab9c0d1e2f3a4b5c6d7e8f",
      "name": "Product Roadmap",
      "description": null,
      "avatar": null,
      "user": {
        "id": "usr_5f9b3c4d8e2a1f0b6c7d8e9f",
        "role": "admin"
      },
      "status": 1,
      "maxFileSize": "50MB"
    }
  ]
}

400

{
  "message": "Bad request.",
  "code": "bad_request",
  "details": [
    {
      "path": "/api/v1/notes/notebooks",
      "message": "Invalid query parameter."
    }
  ]
}

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

403

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

Get notebook details

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

Returns the metadata of a single notebook, including its name, description, avatar, status, and the role of the requesting user inside the notebook.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The notebook ID

cURL

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

TypeScript SDK

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.notebooks.get('nb_64f8a2b1c3d4e5f6a7b8c9d0');

200

{
  "id": "nb_64f8a2b1c3d4e5f6a7b8c9d0",
  "name": "Engineering Wiki",
  "description": "Shared documentation for the engineering team.",
  "avatar": "https://cdn.example.com/avatars/eng-wiki.png",
  "user": {
    "id": "usr_5f9b3c4d8e2a1f0b6c7d8e9f",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "50MB"
}

400

{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": [
    {
      "path": "/api/v1/notes/notebooks",
      "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

403

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

404

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

Create a notebook

POST /api/v1/notes/notebooks

Creates a new notebook with the supplied name, description, and avatar. The requesting user becomes the owner of the new notebook.

Request Body

Name	Type	Required	Description
name	string	Yes	Display name of the notebook
description	string (nullable)	No	Optional description shown on the notebook overview; pass null to leave it unset
avatar	string (nullable)	No	Optional URL to an avatar image; pass null to leave it unset

cURL

curl -X POST 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Engineering Wiki",
    "description": "Shared documentation for the engineering team.",
    "avatar": "https://cdn.example.com/avatars/eng-wiki.png"
  }'

TypeScript SDK

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.notebooks.create({
  name: 'Engineering Wiki',
  description: 'Shared documentation for the engineering team.',
  avatar: 'https://cdn.example.com/avatars/eng-wiki.png'
});

200

{
  "id": "nb_64f8a2b1c3d4e5f6a7b8c9d0",
  "name": "Engineering Wiki",
  "description": "Shared documentation for the engineering team.",
  "avatar": "https://cdn.example.com/avatars/eng-wiki.png",
  "user": {
    "id": "usr_5f9b3c4d8e2a1f0b6c7d8e9f",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "50MB"
}

400

{
  "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 the name, description, or avatar of an existing notebook. Only the notebook owner can update these settings.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The notebook ID

Request Body

Name	Type	Required	Description
name	string	Yes	New display name for the notebook
description	string (nullable)	No	New description; pass null to clear it
avatar	string (nullable)	No	New avatar URL; pass null to clear it

cURL

curl -X PATCH 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/nb_64f8a2b1c3d4e5f6a7b8c9d0' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Engineering Wiki (2025)",
    "description": "Shared documentation for the engineering team, refreshed.",
    "avatar": null
  }'

TypeScript SDK

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.notebooks.update('nb_64f8a2b1c3d4e5f6a7b8c9d0', {
  name: 'Engineering Wiki (2025)',
  description: 'Shared documentation for the engineering team, refreshed.',
  avatar: null
});

200

{
  "id": "nb_64f8a2b1c3d4e5f6a7b8c9d0",
  "name": "Engineering Wiki (2025)",
  "description": "Shared documentation for the engineering team, refreshed.",
  "avatar": null,
  "user": {
    "id": "usr_5f9b3c4d8e2a1f0b6c7d8e9f",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "50MB"
}

400

{
  "message": "Invalid request body.",
  "code": "bad_request",
  "details": [
    {
      "path": "/name",
      "message": "Notebook name cannot be empty."
    }
  ]
}

403

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

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

500

{
  "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 of its data. Only the notebook owner can delete a notebook.

Caution

Deletion is permanent. All notes, files, and membership records inside the notebook are removed and cannot be recovered.

Parameters

Name	In	Type	Required	Description
notebookId	path	string	Yes	The notebook ID

cURL

curl -X DELETE 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/nb_64f8a2b1c3d4e5f6a7b8c9d0' \
  -H 'Authorization: Bearer <token>'

TypeScript SDK

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.notebooks.delete('nb_64f8a2b1c3d4e5f6a7b8c9d0');

200

{
  "id": "nb_64f8a2b1c3d4e5f6a7b8c9d0",
  "name": "Engineering Wiki",
  "description": "Shared documentation for the engineering team.",
  "avatar": "https://cdn.example.com/avatars/eng-wiki.png",
  "user": {
    "id": "usr_5f9b3c4d8e2a1f0b6c7d8e9f",
    "role": "owner"
  },
  "status": 3,
  "maxFileSize": "50MB"
}

400

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

403

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

404

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