Notes: Real-time & Sync

Identity

`GET /api/v1/notes/me`

Returns the current user identity including userId, username, role, and notebookId. Auto-provisions the user and notebook on first call. Call this before opening a socket or syncing mutations to ensure the session is initialized.

This endpoint takes no parameters.

curl -X GET https://api.hoody.com/api/v1/notes/me \
  -H "Authorization: Bearer <token>"

const identity = await client.notes.identity.get();

{
  "userId": "usr_8f2a1c9b3d4e5f60",
  "username": "alex.morgan",
  "role": "editor",
  "notebookId": "ntb_4b7e2d1a9c8f3601"
}

Sockets

WebSocket connections are established in two steps: first initialize a session to receive a socketId, then upgrade the HTTP connection to a WebSocket using that ID.

`POST /api/v1/notes/sockets`

Creates a new socket session and returns the socket ID used to open a WebSocket connection.

This endpoint takes no parameters.

curl -X POST https://api.hoody.com/api/v1/notes/sockets \
  -H "Authorization: Bearer <token>"

const session = await client.notes.sockets.init();
const socketId = session.id;

{
  "id": "sock_a1b2c3d4e5f60718"
}

{
  "message": "Invalid request",
  "code": "BAD_REQUEST",
  "details": [
    {
      "path": "headers",
      "message": "Missing Authorization header"
    }
  ]
}

{
  "message": "Internal server error",
  "code": "INTERNAL_ERROR",
  "details": []
}

`GET /api/v1/notes/sockets/{socketId}`

Upgrades an HTTP connection to a WebSocket using a previously initialized socket ID. The server processes bidirectional messages including cursor movements, node updates, reactions, and document edits.

Parameters

Name	In	Type	Required	Description
`socketId`	path	string	Yes	The socket session ID returned by `POST /api/v1/notes/sockets`

curl -X GET https://api.hoody.com/api/v1/notes/sockets/sock_a1b2c3d4e5f60718 \
  -H "Authorization: Bearer <token>" \
  -H "Upgrade: websocket" \
  -H "Connection: Upgrade"

const ws = await client.notes.sockets.open({
  socketId: "sock_a1b2c3d4e5f60718"
});

{
  "message": "Invalid socket ID",
  "code": "INVALID_SOCKET_ID",
  "details": [
    {
      "path": "params.socketId",
      "message": "Socket ID not found or expired"
    }
  ]
}

{
  "message": "WebSocket upgrade failed",
  "code": "WS_UPGRADE_FAILED",
  "details": []
}

Mutation Sync

`POST /api/v1/notes/notebooks/{notebookId}/mutations`

Processes a batch of client-side mutations — including node CRUD, reactions, interactions, and document edits. Batches can contain up to 500 mutations.

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	The notebook to which mutations should be applied

Request Body

Name	Type	Required	Description
`mutations`	array	Yes	An array of mutation objects (max 500 items). Each entry has a `type` discriminator — supported types include `node.create`, `node.update`, `node.delete`, `node.reaction.create`, `node.reaction.delete`, `node.interaction.seen`, `node.interaction.opened`, and `document.update`.

{
  "mutations": [
    {
      "id": "mut_01HQ7X2E5R8T9K3F",
      "createdAt": "2026-01-15T14:22:09.481Z",
      "type": "node.create",
      "data": {
        "nodeId": "node_9c4a1e2b7f8d3061",
        "updateId": "upd_3a7f1b9d4c8e0252",
        "createdAt": "2026-01-15T14:22:09.481Z",
        "data": "eyJ0eXBlIjoicGFyYWdyYXBoIn0="
      }
    },
    {
      "id": "mut_01HQ7X2E5R8T9K3G",
      "createdAt": "2026-01-15T14:22:10.112Z",
      "type": "node.reaction.create",
      "data": {
        "nodeId": "node_9c4a1e2b7f8d3061",
        "reaction": "👍",
        "rootId": "node_root_4d8e2a1c9b0f7352",
        "createdAt": "2026-01-15T14:22:10.112Z"
      }
    },
    {
      "id": "mut_01HQ7X2E5R8T9K3H",
      "createdAt": "2026-01-15T14:22:11.503Z",
      "type": "node.interaction.seen",
      "data": {
        "nodeId": "node_9c4a1e2b7f8d3061",
        "collaboratorId": "usr_8f2a1c9b3d4e5f60",
        "seenAt": "2026-01-15T14:22:11.503Z"
      }
    }
  ]
}

curl -X POST https://api.hoody.com/api/v1/notes/notebooks/ntb_4b7e2d1a9c8f3601/mutations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mutations": [
      {
        "id": "mut_01HQ7X2E5R8T9K3F",
        "createdAt": "2026-01-15T14:22:09.481Z",
        "type": "node.create",
        "data": {
          "nodeId": "node_9c4a1e2b7f8d3061",
          "updateId": "upd_3a7f1b9d4c8e0252",
          "createdAt": "2026-01-15T14:22:09.481Z",
          "data": "eyJ0eXBlIjoicGFyYWdyYXBoIn0="
        }
      }
    ]
  }'

const result = await client.notes.mutations.sync({
  notebookId: "ntb_4b7e2d1a9c8f3601",
  data: {
    mutations: [
      {
        id: "mut_01HQ7X2E5R8T9K3F",
        createdAt: "2026-01-15T14:22:09.481Z",
        type: "node.create",
        data: {
          nodeId: "node_9c4a1e2b7f8d3061",
          updateId: "upd_3a7f1b9d4c8e0252",
          createdAt: "2026-01-15T14:22:09.481Z",
          data: "eyJ0eXBlIjoicGFyYWdyYXBoIn0="
        }
      }
    ]
  }
});

{}