# Notes: Real-time & Sync

**Page:** api/notes/realtime

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

---

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



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



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


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


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



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


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


```json
{
  "id": "sock_a1b2c3d4e5f60718"
}
```


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


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



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


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


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


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

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



```bash
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="
        }
      }
    ]
  }'
```


```ts
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="
        }
      }
    ]
  }
});
```


```json
{}
```




  Batch mutations efficiently — sending up to 500 mutations in a single request reduces round-trips and improves sync throughput. Assign each mutation a unique `id` so you can correlate it with server-side processing.