# hoody-notes Subskill ## Overview ### Service Purpose Hoody Notes is a collaborative document and knowledge management service within the Hoody ecosystem. It provides structured storage for notebooks, nodes (pages, sections, channels, messages, databases, records), documents, files, comments, reactions, and version history. The service enables real-time collaboration through WebSocket connections and supports rich content editing with block-based documents. ### When to Use hoody-notes Use hoody-notes when you need to: - **Create and manage notebooks** — Organize content into isolated workspaces - **Build document hierarchies** — Create pages, sections, channels, and databases as nodes - **Edit rich documents** — Work with block-based content (text, drawings, embeds) - **Manage file uploads** — Handle resumable uploads via TUS protocol - **Enable collaboration** — Add collaborators, manage permissions, track interactions - **Add comments and reactions** — Enable threaded discussions and emoji reactions - **Track document versions** — Create snapshots and restore previous versions - **Work with databases** — Create structured records with custom fields - **Real-time updates** — Connect via WebSocket for live synchronization ### Service Architecture Hoody Notes follows the standard Hoody Kit service pattern: ``` https://{projectId}-{containerId}-notes-{serviceId}.{node}.containers.hoody.icu ``` All operations target a specific container using `-c ` or the `HOODY_CONTAINER` environment variable. The service auto-provisions users and their default notebook on first identity request. ### Integration with Hoody Philosophy - **Zero configuration** — Automatic DNS, SSL, and authentication via Hoody Proxy - **Container isolation** — Each service instance is fully isolated - **CLI-first** — All operations use `hoody notes ` syntax - **Structured data** — JSON-based documents with block-level granularity - **Collaborative by default** — Built-in multi-user support with role-based access --- ## Common Workflows ### 1. Service Health and Identity #### Check Service Health Verify the notes service is running and responsive: ``` hoody notes health -c ``` Expected response includes service identity, build timestamps, memory usage, and process information. ``` { "service": "notes", "version": "1.0.0", "status": "healthy", "uptime": 86400, "memory": { "rss": 52428800, "heapUsed": 31457280 }, "pid": 1234 } ``` #### Get Current User Identity Retrieve the authenticated user's identity. This auto-provisions the user and default notebook on first call: ``` hoody notes me -c ``` ``` { "userId": "usr_abc123def456", "username": "developer", "role": "owner", "notebookId": "nb_xyz789abc123" } ``` **Important**: Save the `notebookId` from this response — it's needed for most subsequent operations. ### 2. Notebook Management #### List All Notebooks Get all notebooks the current user is a member of: ``` hoody notes notebook list -c ``` ``` [ { "notebookId": "nb_xyz789abc123", "name": "My Workspace", "description": "Personal notes", "status": "active", "role": "owner", "createdAt": "2025-01-15T10:30:00Z" } ] ``` #### Create a New Notebook Create a notebook with name and optional description: ``` hoody notes notebook create -c \ --name "Project Documentation" \ --description "Technical docs for Project Alpha" ``` ``` { "notebookId": "nb_new123abc456", "name": "Project Documentation", "description": "Technical docs for Project Alpha", "status": "active", "role": "owner", "createdAt": "2025-11-05T14:22:00Z" } ``` #### Get Notebook Details Retrieve metadata for a specific notebook: ``` hoody notes notebook get -c \ --notebook-id nb_new123abc456 ``` #### Update Notebook Modify notebook name or description (owner only): ``` hoody notes notebook update -c \ --notebook-id nb_new123abc456 \ --name "Project Alpha Docs" \ --description "Updated technical documentation" ``` #### Delete Notebook Permanently remove a notebook and all its data (owner only): ``` hoody notes notebook delete -c \ --notebook-id nb_new123abc456 ``` **Warning**: This operation is irreversible and deletes all nodes, documents, files, and comments. ### 3. Node Operations #### List Nodes in Notebook Get all nodes with optional filtering: ``` hoody notes node list -c \ --notebook-id nb_xyz789abc123 ``` ``` [ { "nodeId": "node_abc123", "type": "page", "attributes": { "name": "Getting Started", "description": "Introduction guide" }, "parentId": null, "createdAt": "2025-11-01T09:00:00Z" }, { "nodeId": "node_def456", "type": "section", "attributes": { "name": "Tutorials" }, "parentId": null, "createdAt": "2025-11-01T09:05:00Z" } ] ``` #### Create a New Node Create a page node with attributes: ``` hoody notes node create -c \ --notebook-id nb_xyz789abc123 \ --type page \ --attributes '{"name": "API Reference", "description": "Endpoint documentation"}' ``` ``` { "nodeId": "node_ghi789", "type": "page", "attributes": { "name": "API Reference", "description": "Endpoint documentation" }, "parentId": null, "createdAt": "2025-11-05T14:30:00Z" } ``` **Node types**: `page`, `section`, `channel`, `message`, `database`, `record` #### Create a Child Node Nest a node under a parent: ``` hoody notes node create -c \ --notebook-id nb_xyz789abc123 \ --type page \ --parent-id node_def456 \ --attributes '{"name": "Authentication Guide"}' ``` #### Get Node by ID Retrieve full node details: ``` hoody notes node get -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` #### Get Node by Alias Resolve a page by its URL-safe alias: ``` hoody notes node get-by-alias -c \ --notebook-id nb_xyz789abc123 \ --alias "api-reference" ``` #### List Child Nodes Get direct children of a node: ``` hoody notes node children -c \ --notebook-id nb_xyz789abc123 \ --node-id node_def456 ``` #### Update Node Attributes Modify node name or description (type and parentId are immutable): ``` hoody notes node update -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --attributes '{"name": "REST API Reference", "description": "Complete endpoint documentation"}' ``` #### Delete Node Permanently remove a node and all associated data: ``` hoody notes node delete -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ### 4. Document Operations #### Get Document Content Retrieve the block-based document for a node: ``` hoody notes document get -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` { "nodeId": "node_ghi789", "content": { "blocks": [ { "id": "blk_001", "type": "heading", "data": { "text": "API Reference", "level": 1 } }, { "id": "blk_002", "type": "paragraph", "data": { "text": "This section documents all available endpoints." } } ] } } ``` #### Create or Replace Document Set document content (replaces existing): ``` hoody notes document put -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content '{ "blocks": [ { "id": "blk_001", "type": "heading", "data": {"text": "API Reference", "level": 1} }, { "id": "blk_002", "type": "paragraph", "data": {"text": "Complete endpoint documentation."} } ] }' ``` #### Patch Document Content Merge content into existing document (preserves existing blocks unless overwritten): ``` hoody notes document patch -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content '{ "blocks": [ { "id": "blk_003", "type": "paragraph", "data": {"text": "Additional content appended."} } ] }' ``` #### Create Export Ticket Generate a short-lived ticket for static HTML export: ``` hoody notes document export-ticket -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` { "ticket": "export_abc123xyz789", "expiresAt": "2025-11-05T15:30:00Z" } ``` #### Render Block as SVG Export a drawing block as SVG image: ``` hoody notes block svg -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --block-id blk_drawing001 ``` ### 5. File Management #### List Files in Notebook Get all uploaded files: ``` hoody notes file list -c \ --notebook-id nb_xyz789abc123 ``` ``` [ { "fileId": "file_abc123", "name": "diagram.png", "contentType": "image/png", "size": 245760, "createdAt": "2025-11-03T11:00:00Z" } ] ``` #### Upload File (TUS Protocol) The TUS protocol supports resumable uploads. The workflow involves: **Step 1**: Create upload session ``` hoody notes file upload -c \ --notebook-id nb_xyz789abc123 \ --file-id file_new001 ``` **Step 2**: Upload file chunks ``` hoody notes file upload-chunk -c \ --notebook-id nb_xyz789abc123 \ --file-id file_new001 \ --data @./document.pdf ``` **Step 3**: Check upload status ``` hoody notes file check -c \ --notebook-id nb_xyz789abc123 \ --file-id file_new001 ``` #### Download File Retrieve file content: ``` hoody notes file get -c \ --notebook-id nb_xyz789abc123 \ --file-id file_abc123 \ -o document.pdf ``` #### Abort Upload Cancel an in-progress upload: ``` hoody notes file abort -c \ --notebook-id nb_xyz789abc123 \ --file-id file_new001 ``` ### 6. Collaboration #### List Collaborators Get all users with access to a node: ``` hoody notes collaborator list -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` [ { "collaboratorId": "collab_001", "userId": "usr_abc123def456", "username": "developer", "role": "admin", "addedAt": "2025-11-01T09:00:00Z" } ] ``` #### Add Collaborator Grant access to a user (requires admin permission): ``` hoody notes collaborator add -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --collaborator-id usr_other456 \ --role editor ``` **Roles**: `viewer`, `editor`, `admin` #### Update Collaborator Role Change a collaborator's permission level: ``` hoody notes collaborator update -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --collaborator-id collab_001 \ --role admin ``` #### Remove Collaborator Revoke access (requires admin permission): ``` hoody notes collaborator remove -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --collaborator-id collab_001 ``` ### 7. Comments #### List Comments Get all comments on a document node: ``` hoody notes comment list -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` [ { "commentId": "cmt_001", "content": "This section needs more detail.", "authorId": "usr_abc123def456", "createdAt": "2025-11-04T16:30:00Z", "resolved": false } ] ``` #### Create Comment Add a comment to a document: ``` hoody notes comment create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content "Consider adding code examples here." ``` #### Get Comment Anchors Retrieve lightweight anchor metadata for comment decorations: ``` hoody notes comment anchors -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` #### Edit Comment Update comment content: ``` hoody notes comment update -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --comment-id cmt_001 \ --content "Updated: This section needs code examples." ``` #### Delete Comment Remove a comment and its replies: ``` hoody notes comment delete -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --comment-id cmt_001 ``` #### Reanchor Comment Update the root anchor for a comment thread: ``` hoody notes comment reanchor -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --comment-id cmt_001 ``` #### Resolve Comment Mark a comment thread as resolved: ``` hoody notes comment resolve -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --comment-id cmt_001 ``` ### 8. Reactions #### List Reactions Get all reactions on a node: ``` hoody notes reaction list -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` [ { "reaction": "👍", "userId": "usr_abc123def456", "username": "developer", "createdAt": "2025-11-04T17:00:00Z" } ] ``` #### Add Reaction Add an emoji reaction: ``` hoody notes reaction add -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --reaction "🎉" ``` #### Remove Reaction Remove your own reaction: ``` hoody notes reaction remove -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --reaction "🎉" ``` ### 9. Interactions #### Record "Seen" Interaction Track that a user has seen a node: ``` hoody notes interaction seen -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` #### Record "Opened" Interaction Track that a user has opened a node: ``` hoody notes interaction opened -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ### 10. Version History #### List Versions Get all document versions ordered by revision: ``` hoody notes version list -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` [ { "versionId": "ver_003", "revision": 3, "createdAt": "2025-11-05T10:00:00Z", "authorId": "usr_abc123def456" }, { "versionId": "ver_002", "revision": 2, "createdAt": "2025-11-04T15:00:00Z", "authorId": "usr_abc123def456" } ] ``` #### Create Version Snapshot Capture current document state: ``` hoody notes version create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` ``` { "versionId": "ver_004", "revision": 4, "createdAt": "2025-11-05T15:00:00Z", "authorId": "usr_abc123def456" } ``` #### Get Specific Version Retrieve a version's content: ``` hoody notes version get -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --version-id ver_002 ``` #### Restore Version Revert document to a previous version: ``` hoody notes version restore -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --version-id ver_002 ``` #### Delete Version Remove a specific version: ``` hoody notes version delete -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --version-id ver_001 ``` ### 11. Database Records #### List Records Get all records in a database node: ``` hoody notes database list-records -c \ --notebook-id nb_xyz789abc123 \ --database-id node_db001 ``` ``` [ { "recordId": "rec_001", "name": "Task Alpha", "fields": { "status": "in-progress", "priority": "high", "assignee": "developer" }, "createdAt": "2025-11-01T10:00:00Z" } ] ``` #### Create Record Add a new record to a database: ``` hoody notes database create-record -c \ --notebook-id nb_xyz789abc123 \ --database-id node_db001 \ --name "Task Beta" \ --fields '{"status": "todo", "priority": "medium", "assignee": "reviewer"}' ``` ``` { "recordId": "rec_002", "name": "Task Beta", "fields": { "status": "todo", "priority": "medium", "assignee": "reviewer" }, "createdAt": "2025-11-05T15:10:00Z" } ``` #### Search Records Search records by name: ``` hoody notes database search-records -c \ --notebook-id nb_xyz789abc123 \ --database-id node_db001 \ --query "Task" ``` #### Get Record Retrieve a single record: ``` hoody notes database get-record -c \ --notebook-id nb_xyz789abc123 \ --database-id node_db001 \ --record-id rec_001 ``` #### Update Record Modify record fields (merged with existing): ``` hoody notes database update-record -c \ --notebook-id nb_xyz789abc123 \ --database-id node_db001 \ --record-id rec_001 \ --name "Task Alpha (Updated)" \ --fields '{"status": "completed"}' ``` #### Delete Record Remove a record permanently: ``` hoody notes database delete-record -c \ --notebook-id nb_xyz789abc123 \ --database-id node_db001 \ --record-id rec_002 ``` ### 12. User Management #### Create Users Add users to a notebook by username: ``` hoody notes user create -c \ --notebook-id nb_xyz789abc123 \ --usernames '["alice", "bob"]' ``` ``` { "created": [ { "userId": "usr_alice001", "username": "alice", "role": "viewer" }, { "userId": "usr_bob002", "username": "bob", "role": "viewer" } ], "errors": [] } ``` #### Update User Role Change a user's notebook role (requires owner or admin): ``` hoody notes user update-role -c \ --notebook-id nb_xyz789abc123 \ --user-id usr_alice001 \ --role editor ``` ### 13. WebSocket Connections #### Initialize Socket Session Create a socket session for real-time updates: ``` hoody notes socket create -c ``` ``` { "socketId": "sock_abc123xyz789" } ``` #### Open WebSocket Connection Upgrade to WebSocket using the socket ID: ``` hoody notes socket open -c \ --socket-id sock_abc123xyz789 ``` ### 14. Avatar Management #### Upload Avatar Upload an image (JPEG, PNG, WebP) as an avatar: ``` hoody notes avatar upload -c \ --file ./profile.png ``` ``` { "avatarId": "avatar_abc123" } ``` #### Download Avatar Retrieve avatar as JPEG: ``` hoody notes avatar get -c \ --avatar-id avatar_abc123 \ -o avatar.jpg ``` ### 15. Batch Mutations #### Process Multiple Operations Execute a batch of mutations in a single request: ``` hoody notes mutation process -c \ --notebook-id nb_xyz789abc123 \ --mutations '[ { "type": "node.create", "data": { "type": "page", "attributes": {"name": "Batch Page 1"} } }, { "type": "node.create", "data": { "type": "page", "attributes": {"name": "Batch Page 2"} } }, { "type": "reaction.add", "data": { "nodeId": "node_ghi789", "reaction": "⭐" } } ]' ``` ``` { "results": [ { "status": "success", "data": { "nodeId": "node_batch001" } }, { "status": "success", "data": { "nodeId": "node_batch002" } }, { "status": "success", "data": { "reaction": "⭐" } } ] } ``` --- ## Advanced Operations ### Complex Multi-Step Workflows #### Workflow: Create a Complete Document Structure This workflow creates a notebook with nested sections, pages, and content: ``` # Step 1: Create notebook NOTEBOOK=$(hoody notes notebook create -c \ --name "Project Docs" \ --description "Complete project documentation" \ -o json) NOTEBOOK_ID=$(echo $NOTEBOOK | jq -r '.notebookId') # Step 2: Create root section SECTION=$(hoody notes node create -c \ --notebook-id $NOTEBOOK_ID \ --type section \ --attributes '{"name": "Getting Started"}' \ -o json) SECTION_ID=$(echo $SECTION | jq -r '.nodeId') # Step 3: Create child page PAGE=$(hoody notes node create -c \ --notebook-id $NOTEBOOK_ID \ --type page \ --parent-id $SECTION_ID \ --attributes '{"name": "Installation Guide"}' \ -o json) PAGE_ID=$(echo $PAGE | jq -r '.nodeId') # Step 4: Add document content hoody notes document put -c \ --notebook-id $NOTEBOOK_ID \ --node-id $PAGE_ID \ --content '{ "blocks": [ { "id": "blk_001", "type": "heading", "data": {"text": "Installation Guide", "level": 1} }, { "id": "blk_002", "type": "paragraph", "data": {"text": "Follow these steps to install the software."} }, { "id": "blk_003", "type": "code", "data": {"text": "npm install @hoody/notes", "language": "bash"} } ] }' # Step 5: Create initial version hoody notes version create -c \ --notebook-id $NOTEBOOK_ID \ --node-id $PAGE_ID # Step 6: Add collaborator hoody notes collaborator add -c \ --notebook-id $NOTEBOOK_ID \ --node-id $PAGE_ID \ --collaborator-id usr_reviewer001 \ --role editor echo "Document structure created successfully" ``` #### Workflow: Document Review Cycle This workflow demonstrates a complete review cycle with comments and versioning: ``` # Step 1: Create version before review hoody notes version create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 # Step 2: Reviewer adds comments hoody notes comment create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content "The introduction needs more context about prerequisites." hoody notes comment create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content "Consider adding a troubleshooting section." # Step 3: Author addresses comments hoody notes document patch -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content '{ "blocks": [ { "id": "blk_new001", "type": "heading", "data": {"text": "Prerequisites", "level": 2} }, { "id": "blk_new002", "type": "paragraph", "data": {"text": "Before installing, ensure you have Node.js 18+ and npm 9+."} } ] }' # Step 4: Resolve comments hoody notes comment resolve -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --comment-id cmt_001 hoody notes comment resolve -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --comment-id cmt_002 # Step 5: Create post-review version hoody notes version create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 # Step 6: Add approval reaction hoody notes reaction add -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --reaction "✅" ``` #### Workflow: Database Migration This workflow creates a database, populates records, and performs bulk operations: ``` # Step 1: Create database node DB=$(hoody notes node create -c \ --notebook-id nb_xyz789abc123 \ --type database \ --attributes '{"name": "Task Tracker", "description": "Project task management"}' \ -o json) DB_ID=$(echo $DB | jq -r '.nodeId') # Step 2: Create records in batch hoody notes mutation process -c \ --notebook-id nb_xyz789abc123 \ --mutations "[ { \"type\": \"record.create\", \"data\": { \"databaseId\": \"$DB_ID\", \"name\": \"Setup CI/CD\", \"fields\": {\"status\": \"todo\", \"priority\": \"high\"} } }, { \"type\": \"record.create\", \"data\": { \"databaseId\": \"$DB_ID\", \"name\": \"Write documentation\", \"fields\": {\"status\": \"in-progress\", \"priority\": \"medium\"} } }, { \"type\": \"record.create\", \"data\": { \"databaseId\": \"$DB_ID\", \"name\": \"Code review\", \"fields\": {\"status\": \"todo\", \"priority\": \"high\"} } } ]" # Step 3: Search for high-priority tasks hoody notes database search-records -c \ --notebook-id nb_xyz789abc123 \ --database-id $DB_ID \ --query "Setup" ``` ### Error Recovery Patterns #### Handling Failed Node Creation If node creation fails, check for existing nodes with the same name: ``` # Attempt creation RESULT=$(hoody notes node create -c \ --notebook-id nb_xyz789abc123 \ --type page \ --attributes '{"name": "My Page"}' \ -o json 2>&1) # Check for errors if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then echo "Creation failed, searching for existing node..." # Find existing node EXISTING=$(hoody notes node list -c \ --notebook-id nb_xyz789abc123 \ -o json | jq '.[] | select(.attributes.name == "My Page")') if [ -n "$EXISTING" ]; then NODE_ID=$(echo "$EXISTING" | jq -r '.nodeId') echo "Found existing node: $NODE_ID" # Update instead of create hoody notes node update -c \ --notebook-id nb_xyz789abc123 \ --node-id $NODE_ID \ --attributes '{"name": "My Page", "description": "Updated description"}' fi else echo "Node created successfully" fi ``` #### Recovering from Document Conflicts When document updates conflict, restore from version and reapply changes: ``` # Step 1: List recent versions VERSIONS=$(hoody notes version list -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ -o json) # Step 2: Get the last known good version LAST_GOOD=$(echo $VERSIONS | jq -r '.[0].versionId') # Step 3: Restore to last good version hoody notes version restore -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --version-id $LAST_GOOD # Step 4: Reapply changes with patch hoody notes document patch -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 \ --content '{ "blocks": [ { "id": "blk_recovered", "type": "paragraph", "data": {"text": "Recovered content after conflict resolution."} } ] }' # Step 5: Create new version hoody notes version create -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` #### Handling Upload Failures Resume interrupted file uploads: ``` # Step 1: Check upload status STATUS=$(hoody notes file check -c \ --notebook-id nb_xyz789abc123 \ --file-id file_abc123 \ -o json) # Step 2: Get upload offset OFFSET=$(echo $STATUS | jq -r '.offset') # Step 3: Resume upload from offset hoody notes file upload-chunk -c \ --notebook-id nb_xyz789abc123 \ --file-id file_abc123 \ --offset $OFFSET \ --data @./large-file.zip ``` ### Performance Considerations #### Batch Operations Use mutations endpoint for bulk operations instead of individual calls: ``` # Instead of 100 individual create calls: # hoody notes node create ... (x100) # Use single batch mutation: hoody notes mutation process -c \ --notebook-id nb_xyz789abc123 \ --mutations '[...]' ``` #### Pagination Use limit and offset for large result sets: ``` # Get first 50 nodes hoody notes node list -c \ --notebook-id nb_xyz789abc123 \ --limit 50 \ --offset 0 # Get next 50 nodes hoody notes node list -c \ --notebook-id nb_xyz789abc123 \ --limit 50 \ --offset 50 ``` #### Filtering Filter nodes by type to reduce payload: ``` # Get only pages hoody notes node list -c \ --notebook-id nb_xyz789abc123 \ --type page # Get only databases hoody notes node list -c \ --notebook-id nb_xyz789abc123 \ --type database ``` #### Caching Strategy Cache frequently accessed data locally: ``` # Cache notebook list (changes infrequently) hoody notes notebook list -c -o json > /tmp/notebooks.json # Cache node structure (changes moderately) hoody notes node list -c \ --notebook-id nb_xyz789abc123 \ -o json > /tmp/nodes.json # Always fetch fresh document content (changes frequently) hoody notes document get -c \ --notebook-id nb_xyz789abc123 \ --node-id node_ghi789 ``` #### Connection Management Reuse WebSocket connections for real-time features: ``` # Initialize socket once SOCKET=$(hoody notes socket create -c -o json) SOCKET_ID=$(echo $SOCKET | jq -r '.socketId') # Store socket ID for reuse echo $SOCKET_ID > /tmp/hoody-socket-id # Reuse in subsequent operations hoody notes socket open -c \ --socket-id $(cat /tmp/hoody-socket-id) ``` --- ## Quick Reference ### Most Common Endpoints | Operation | CLI Command | |-----------|-------------| | Check health | `hoody notes health -c ` | | Get identity | `hoody notes me -c ` | | List notebooks | `hoody notes notebook list -c ` | | Create notebook | `hoody notes notebook create -c --name "..."` | | List nodes | `hoody notes node list -c --notebook-id ` | | Create node | `hoody notes node create -c --notebook-id --type page --attributes '{...}'` | | Get document | `hoody notes document get -c --notebook-id --node-id ` | | Update document | `hoody notes document put -c --notebook-id --node-id --content '{...}'` | | List comments | `hoody notes comment list -c --notebook-id --node-id ` | | Create version | `hoody notes version create -c --notebook-id --node-id ` | ### Essential Parameters | Parameter | Description | Example | |-----------|-------------|---------| | `-c ` | Target container | `-c cnt_abc123` | | `--notebook-id ` | Notebook identifier | `--notebook-id nb_xyz789` | | `--node-id ` | Node identifier | `--node-id node_ghi789` | | `--type ` | Node type | `--type page` | | `--role ` | Permission role | `--role editor` | | `-o json` | JSON output format | `-o json` | ### Typical Response Formats **Single Resource:** ``` { "id": "resource_abc123", "type": "page", "attributes": { "name": "Resource Name" }, "createdAt": "2025-11-05T15:00:00Z" } ``` **List Response:** ``` [ { "id": "resource_001", "name": "Item 1" }, { "id": "resource_002", "name": "Item 2" } ] ``` **Error Response:** ``` { "error": { "code": "NOT_FOUND", "message": "Node not found", "details": { "nodeId": "node_invalid" } } } ``` **Mutation Response:** ``` { "results": [ { "status": "success", "data": { "id": "created_001" } }, { "status": "error", "error": { "code": "VALIDATION_ERROR", "message": "Invalid field value" } } ] } ``` ### Node Types | Type | Description | Use Case | |------|-------------|----------| | `page` | Document page | Main content pages | | `section` | Container for pages | Organizational grouping | | `channel` | Communication channel | Team discussions | | `message` | Single message | Chat messages | | `database` | Structured data store | Tables, spreadsheets | | `record` | Database row | Individual data entries | ### Collaborator Roles | Role | Permissions | |------|-------------| | `viewer` | Read-only access | | `editor` | Read and write access | | `admin` | Full access including collaborator management | ### Common Flags | Flag | Description | |------|-------------| | `--limit ` | Number of results to return | | `--offset ` | Number of results to skip | | `--query ` | Search query string | | `--fields '{...}'` | JSON object of field values | | `--content '{...}'` | JSON object of document content | | `--attributes '{...}'` | JSON object of node attributes |