Notes: File Uploads

Upload, download, and manage files and avatars attached to notebooks. This page covers the avatar endpoints, the file listing and download endpoints, and the resumable TUS upload protocol used for notebook attachments.

Avatars

Avatars are user profile images. The upload endpoint accepts JPEG, PNG, or WebP images, which are resized to 500x500 and stored as JPEG. The download endpoint returns the binary image data.

`POST /api/v1/notes/avatars`

Uploads a raw image as an avatar. The image is resized to 500x500 and converted to JPEG.

This endpoint takes no parameters.

The request body is a multipart form upload containing the image file (JPEG, PNG, or WebP).

curl -X POST https://api.hoody.com/api/v1/notes/avatars \
  -H "Authorization: Bearer &lt;token&gt;" \
  -F "avatar=@/path/to/photo.jpg"

const result = await client.notes.avatars.upload();

{
  "success": true,
  "id": "avatar_01HXYZABCDEF123456"
}

{
  "message": "No avatar file was uploaded.",
  "code": "avatar_file_not_uploaded"
}

Error Code	Title	Description	Resolution
`avatar_file_not_uploaded`	Invalid upload	No file was uploaded or the content type is not a valid image	Send a multipart form with a JPEG or PNG image file

{
  "message": "Failed to upload avatar.",
  "code": "avatar_upload_failed"
}

Error Code	Title	Description	Resolution
`avatar_upload_failed`	Upload failed	Avatar upload failed due to a server error	Retry the upload

`GET /api/v1/notes/avatars/{avatarId}`

Returns the avatar image as JPEG binary data.

Parameters

Name	In	Type	Required	Description
`avatarId`	path	string	Yes	The ID of the avatar to download

curl -X GET https://api.hoody.com/api/v1/notes/avatars/avatar_01HXYZABCDEF123456 \
  -H "Authorization: Bearer &lt;token&gt;" \
  -o avatar.jpg

const stream = await client.notes.avatars.download({
  avatarId: "avatar_01HXYZABCDEF123456"
});

{
  "description": "Default Response"
}

The response body is the raw JPEG binary.

Files

Files are attachments stored within a notebook. List and download operations are straightforward, while uploads use the resumable TUS protocol for reliability on large or unstable connections.

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

Returns a paginated list of files uploaded to a notebook. Supports limit/offset pagination.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The ID of the notebook
`limit`	query	integer	No	Maximum number of files to return (default: `50`)
`offset`	query	integer	No	Number of files to skip (default: `0`)

curl -X GET "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXYZABCDEF123456/files?limit=50&offset=0" \
  -H "Authorization: Bearer &lt;token&gt;"

const page = await client.notes.files.listIterator({
  notebookId: "ntb_01HXYZABCDEF123456",
  limit: 50,
  offset: 0
});

{
  "files": [
    {
      "id": "file_01HXYZABCDEF123456",
      "name": "meeting-notes.pdf",
      "mimeType": "application/pdf",
      "size": 245678,
      "createdAt": "2025-01-15T14:32:11.000Z",
      "createdBy": "user_01HXYZABCDEF000001",
      "documentId": "doc_01HXYZABCDEF123456",
      "documentName": "Q4 Planning"
    },
    {
      "id": "file_01HXYZABCDEF789012",
      "name": "screenshot.png",
      "mimeType": "image/png",
      "size": 124530,
      "createdAt": "2025-01-16T09:15:42.000Z",
      "createdBy": "user_01HXYZABCDEF000002",
      "documentId": "doc_01HXYZABCDEF789012",
      "documentName": null
    }
  ],
  "total": 2
}

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

Error Code	Title	Description	Resolution
`notebook_not_found`	Notebook not found	No notebook exists with the provided ID	Verify notebook ID using `listNotebooks`
`notebook_no_access`	Access denied	User does not have permission to access files in this notebook	Check collaborator list or request access from the notebook owner

`GET /api/v1/notes/notebooks/{notebookId}/files/{fileId}`

Downloads the content of an uploaded file. Returns the binary data with the original content type.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The ID of the notebook
`fileId`	path	string	Yes	The ID of the file to download

curl -X GET "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXYZABCDEF123456/files/file_01HXYZABCDEF123456" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -o meeting-notes.pdf

const stream = await client.notes.files.download({
  notebookId: "ntb_01HXYZABCDEF123456",
  fileId: "file_01HXYZABCDEF123456"
});

{
  "description": "Default Response"
}

The response body is the raw file binary, returned with the original Content-Type (for example, application/pdf or image/png).

TUS Resumable Uploads

Large file uploads are handled through the TUS protocol, which supports resumable uploads via four HTTP methods on the same endpoint. Use the TUS client library of your choice, or the SDK wrappers below.

`POST /api/v1/notes/notebooks/{notebookId}/files/{fileId}/tus`

Creates a new resumable upload. Returns a Location header containing the upload URL to use for subsequent PATCH requests.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The ID of the notebook
`fileId`	path	string	Yes	The ID of the file

curl -X POST "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXYZABCDEF123456/files/file_01HXYZABCDEF123456/tus" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Length: 245678" \
  -H "Upload-Metadata: filename bWVldGluZy1ub3Rlcy5wZGY="

const upload = await client.notes.files.tusCreateUpload({
  notebookId: "ntb_01HXYZABCDEF123456",
  fileId: "file_01HXYZABCDEF123456"
});

{
  "description": "Default Response"
}

`PATCH /api/v1/notes/notebooks/{notebookId}/files/{fileId}/tus`

Uploads a chunk of the file. Repeat this call until the full Upload-Length has been transferred.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	notebookId path parameter
`fileId`	path	string	Yes	fileId path parameter

curl -X PATCH "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXYZABCDEF123456/files/file_01HXYZABCDEF123456/tus" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Tus-Resumable: 1.0.0" \
  -H "Upload-Offset: 0" \
  -H "Content-Type: application/offset+octet-stream" \
  --data-binary @chunk-0.bin

await client.notes.files.tusUploadChunk({
  notebookId: "ntb_01HXYZABCDEF123456",
  fileId: "file_01HXYZABCDEF123456"
});

{
  "description": "Default Response"
}

`HEAD /api/v1/notes/notebooks/{notebookId}/files/{fileId}/tus`

Returns the current Upload-Offset so a client can resume a paused upload without re-sending already-written bytes.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The ID of the notebook
`fileId`	path	string	Yes	The ID of the file

curl -X HEAD "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXYZABCDEF123456/files/file_01HXYZABCDEF123456/tus" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Tus-Resumable: 1.0.0"

const offset = await client.notes.files.tusCheckUpload({
  notebookId: "ntb_01HXYZABCDEF123456",
  fileId: "file_01HXYZABCDEF123456"
});

{
  "description": "Default Response"
}

`DELETE /api/v1/notes/notebooks/{notebookId}/files/{fileId}/tus`

Aborts an in-progress upload and discards any bytes already received.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	notebookId path parameter
`fileId`	path	string	Yes	fileId path parameter

curl -X DELETE "https://api.hoody.com/api/v1/notes/notebooks/ntb_01HXYZABCDEF123456/files/file_01HXYZABCDEF123456/tus" \
  -H "Authorization: Bearer &lt;token&gt;" \
  -H "Tus-Resumable: 1.0.0"

await client.notes.files.tusAbortUpload({
  notebookId: "ntb_01HXYZABCDEF123456",
  fileId: "file_01HXYZABCDEF123456"
});

{
  "description": "Default Response"
}