Notes: Notebooks

Use these endpoints to manage notebooks, which are the top-level container for notes and pages. You can list notebooks accessible to the current user, retrieve a single notebook, create new ones, update settings, or delete them. Notebook membership is role-based, where only owners can update or delete a notebook.

List notebooks

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

GET /api/v1/notes/notebooks

This endpoint takes no parameters.

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

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

{
  "notebooks": [
    {
      "id": "nb_8f3c2a1b9d4e4f7a",
      "name": "Project Roadmap",
      "description": "Quarterly planning and milestones",
      "avatar": null,
      "user": {
        "id": "user_01HQXK7G2N3R5V8Y",
        "role": "owner"
      },
      "status": 1,
      "maxFileSize": "10mb"
    },
    {
      "id": "nb_2e9d8c7b6a5f4e3d",
      "name": "Engineering Wiki",
      "description": null,
      "avatar": "https://cdn.example.com/avatars/eng-wiki.png",
      "user": {
        "id": "user_01HQXK7G2N3R5V8Y",
        "role": "collaborator"
      },
      "status": 1,
      "maxFileSize": "25mb"
    }
  ]
}

{
  "code": "bad_request",
  "message": "Bad request."
}

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

{
  "code": "forbidden",
  "message": "You do not have permission to perform this action."
}

Get notebook details

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

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

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.com/api/v1/notes/notebooks/nb_8f3c2a1b9d4e4f7a' \
  -H 'Authorization: Bearer <token>'

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_8f3c2a1b9d4e4f7a');

{
  "id": "nb_8f3c2a1b9d4e4f7a",
  "name": "Project Roadmap",
  "description": "Quarterly planning and milestones",
  "avatar": null,
  "user": {
    "id": "user_01HQXK7G2N3R5V8Y",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10mb"
}

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

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

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

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

Create a notebook

Creates a new notebook owned by the requesting user. The name field is required.

POST /api/v1/notes/notebooks

Request body

Name	In	Type	Required	Description
`name`	body	string	Yes	Display name for the notebook
`description`	body	string \| null	No	Optional longer description
`avatar`	body	string \| null	No	Optional avatar URL or identifier

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

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": "Product Launch Plan",
    "description": "Tracking the v2.0 launch tasks and owners",
    "avatar": null
  }'

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: 'Product Launch Plan',
  description: 'Tracking the v2.0 launch tasks and owners',
  avatar: null,
});

{
  "id": "nb_4d2e1c9f8a7b6e5d",
  "name": "Product Launch Plan",
  "description": "Tracking the v2.0 launch tasks and owners",
  "avatar": null,
  "user": {
    "id": "user_01HQXK7G2N3R5V8Y",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10mb"
}

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

Updates the name, description, or avatar of an existing notebook. Only owners (and admins, where applicable) can update notebook settings.

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

Parameters

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

Request body

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

curl -X PATCH 'https://{projectId}-{containerId}-notes-1.{server}.containers.hoody.com/api/v1/notes/notebooks/nb_4d2e1c9f8a7b6e5d' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product Launch Plan (v2)",
    "description": "Updated scope for the v2.0 launch",
    "avatar": null
  }'

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_4d2e1c9f8a7b6e5d', {
  name: 'Product Launch Plan (v2)',
  description: 'Updated scope for the v2.0 launch',
  avatar: null,
});

{
  "id": "nb_4d2e1c9f8a7b6e5d",
  "name": "Product Launch Plan (v2)",
  "description": "Updated scope for the v2.0 launch",
  "avatar": null,
  "user": {
    "id": "user_01HQXK7G2N3R5V8Y",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10mb"
}

{
  "code": "bad_request",
  "message": "Invalid request body."
}

{
  "code": "notebook_update_not_allowed",
  "message": "You do not have permission to update this notebook."
}

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
`notebook_no_access`	No access to notebook	The notebook exists but the caller is not a member, or it is not open	Verify user identity or request access from the owner

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

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

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

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

Permanently deletes a notebook and all of its data. Only the notebook owner can delete it.

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

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.com/api/v1/notes/notebooks/nb_4d2e1c9f8a7b6e5d' \
  -H 'Authorization: Bearer <token>'

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_4d2e1c9f8a7b6e5d');

{
  "id": "nb_4d2e1c9f8a7b6e5d",
  "name": "Product Launch Plan (v2)",
  "description": "Updated scope for the v2.0 launch",
  "avatar": null,
  "user": {
    "id": "user_01HQXK7G2N3R5V8Y",
    "role": "owner"
  },
  "status": 3,
  "maxFileSize": "10mb"
}

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

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
`notebook_no_access`	No access to notebook	The notebook exists but the caller is not a member, or it is not open	Verify user identity or request access from the owner

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

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

Response fields

The notebook object returned by the endpoints above shares a common shape:

Field	Type	Required	Description
`id`	string	Yes	Notebook identifier
`name`	string	Yes	Display name of the notebook
`description`	string \| null	No	Optional longer description
`avatar`	string \| null	No	Avatar URL or identifier
`user`	object	Yes	Current user’s relationship to the notebook
`user.id`	string	Yes	Current user identifier
`user.role`	string	Yes	Role of the current user: `owner`, `admin`, `collaborator`, `guest`, or `none`
`status`	number	Yes	Notebook status: `1` (active), `2` (archived), or `3` (deleted)
`maxFileSize`	string	No	Maximum upload size, formatted as a string with units

Error responses share a common shape:

Field	Type	Required	Description
`message`	string	Yes	Human-readable error message
`code`	string	Yes	Machine-readable error code
`details`	array	No	Array of per-path validation errors
`details[].path`	string	Yes	Field path that failed validation
`details[].message`	string	Yes	Description of the validation failure