# Notes: Notebooks

**Page:** api/notes/notebooks

[Download Raw Markdown](./api/notes/notebooks.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Notes Notebooks API lets you manage notebook resources, which are containers for notes and files within a workspace. Use these endpoints to list, create, retrieve, update, and delete notebooks that the current user has access to. Each notebook exposes membership information for the requesting user (`role`: `owner`, `admin`, `collaborator`, `guest`, or `none`).

---

## 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.



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


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


```json
{
  "notebooks": [
    {
      "id": "5f8d3b2a1c9d4e5f6a7b8c9d",
      "name": "Research Notes",
      "description": "Notes for the Q4 research project",
      "avatar": null,
      "user": {
        "id": "6a1e5f9c2b3d4e5f6a7b8c9d",
        "role": "owner"
      },
      "status": 1,
      "maxFileSize": "10485760"
    },
    {
      "id": "7b2c4d5e6f7a8b9c0d1e2f3a",
      "name": "Personal Journal",
      "description": null,
      "avatar": null,
      "user": {
        "id": "6a1e5f9c2b3d4e5f6a7b8c9d",
        "role": "collaborator"
      },
      "status": 1,
      "maxFileSize": "5242880"
    }
  ]
}
```


```json
{
  "message": "Bad request.",
  "code": "bad_request",
  "details": [
    {
      "path": ["query"],
      "message": "Invalid query parameter"
    }
  ]
}
```

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


```json
{
  "message": "Forbidden.",
  "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 within the notebook.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `notebookId` | path | string | Yes | The unique identifier of the notebook to retrieve |



```bash
curl -X GET 'https://api.hoody.com/api/v1/notes/notebooks/5f8d3b2a1c9d4e5f6a7b8c9d' \
  -H 'Authorization: Bearer <token>'
```


```js
const notebook = await client.notes.notebooks.get('5f8d3b2a1c9d4e5f6a7b8c9d');
```


```json
{
  "id": "5f8d3b2a1c9d4e5f6a7b8c9d",
  "name": "Research Notes",
  "description": "Notes for the Q4 research project",
  "avatar": null,
  "user": {
    "id": "6a1e5f9c2b3d4e5f6a7b8c9d",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10485760"
}
```


```json
{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": [
    {
      "path": ["params", "notebookId"],
      "message": "Invalid notebook ID"
    }
  ]
}
```

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


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


```json
{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": [
    {
      "path": ["params", "notebookId"],
      "message": "No notebook matches the provided ID"
    }
  ]
}
```



---

## Create a notebook

`POST /api/v1/notes/notebooks`

Creates a new notebook with the given name, description, and avatar. The requesting user becomes the `owner` of the newly created notebook.

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | The display name of the notebook. Must be non-empty. |
| `description` | string \| null | No | An optional description of the notebook |
| `avatar` | string \| null | No | An optional avatar identifier or URL for the notebook |

```json
{
  "name": "Research Notes",
  "description": "Notes for the Q4 research project",
  "avatar": null
}
```



```bash
curl -X POST 'https://api.hoody.com/api/v1/notes/notebooks' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Research Notes",
    "description": "Notes for the Q4 research project",
    "avatar": null
  }'
```


```js
const notebook = await client.notes.notebooks.create({
  name: "Research Notes",
  description: "Notes for the Q4 research project",
  avatar: null
});
```


```json
{
  "id": "5f8d3b2a1c9d4e5f6a7b8c9d",
  "name": "Research Notes",
  "description": "Notes for the Q4 research project",
  "avatar": null,
  "user": {
    "id": "6a1e5f9c2b3d4e5f6a7b8c9d",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10485760"
}
```


```json
{
  "message": "Notebook name is required.",
  "code": "notebook_name_required",
  "details": [
    {
      "path": ["body", "name"],
      "message": "Name is required and cannot 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 |



---

## Update notebook settings

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

Updates a notebook's name, description, or avatar. Only the notebook `owner` (and users with administrative roles) can update its settings.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `notebookId` | path | string | Yes | The unique identifier of the notebook to update |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | The new display name of the notebook. Must be non-empty. |
| `description` | string \| null | No | The new description of the notebook |
| `avatar` | string \| null | No | The new avatar identifier or URL for the notebook |

```json
{
  "name": "Research Notes (2024)",
  "description": "Updated notes for the Q4 research project",
  "avatar": null
}
```



```bash
curl -X PATCH 'https://api.hoody.com/api/v1/notes/notebooks/5f8d3b2a1c9d4e5f6a7b8c9d' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Research Notes (2024)",
    "description": "Updated notes for the Q4 research project",
    "avatar": null
  }'
```


```js
const notebook = await client.notes.notebooks.update('5f8d3b2a1c9d4e5f6a7b8c9d', {
  name: "Research Notes (2024)",
  description: "Updated notes for the Q4 research project",
  avatar: null
});
```


```json
{
  "id": "5f8d3b2a1c9d4e5f6a7b8c9d",
  "name": "Research Notes (2024)",
  "description": "Updated notes for the Q4 research project",
  "avatar": null,
  "user": {
    "id": "6a1e5f9c2b3d4e5f6a7b8c9d",
    "role": "owner"
  },
  "status": 1,
  "maxFileSize": "10485760"
}
```


```json
{
  "message": "Notebook name is required.",
  "code": "notebook_name_required",
  "details": [
    {
      "path": ["body", "name"],
      "message": "Name is required and cannot be empty"
    }
  ]
}
```


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


```json
{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": [
    {
      "path": ["params", "notebookId"],
      "message": "No notebook matches the provided ID"
    }
  ]
}
```


```json
{
  "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. This action is irreversible. Only the notebook `owner` can delete it.

### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `notebookId` | path | string | Yes | The unique identifier of the notebook to delete |



```bash
curl -X DELETE 'https://api.hoody.com/api/v1/notes/notebooks/5f8d3b2a1c9d4e5f6a7b8c9d' \
  -H 'Authorization: Bearer <token>'
```


```js
await client.notes.notebooks.delete('5f8d3b2a1c9d4e5f6a7b8c9d');
```


```json
{
  "id": "5f8d3b2a1c9d4e5f6a7b8c9d",
  "name": "Research Notes",
  "description": "Notes for the Q4 research project",
  "avatar": null,
  "user": {
    "id": "6a1e5f9c2b3d4e5f6a7b8c9d",
    "role": "owner"
  },
  "status": 3,
  "maxFileSize": "10485760"
}
```


```json
{
  "message": "Invalid request.",
  "code": "bad_request",
  "details": [
    {
      "path": ["params", "notebookId"],
      "message": "Invalid notebook ID"
    }
  ]
}
```


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


```json
{
  "message": "Notebook not found.",
  "code": "notebook_not_found",
  "details": [
    {
      "path": ["params", "notebookId"],
      "message": "No notebook matches the provided ID"
    }
  ]
}
```

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




Deleting a notebook is permanent. All notes, files, and membership data associated with the notebook are removed and cannot be recovered.