Velt

https://velt.dev/docs
Admin
Velt is a collaboration platform that enables async and realtime collaboration features including...
Tokens:1,351,415
Snippets:13,760
Trust Score:7.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize and Configure ProseMirror Collaboration

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/prosemirror

This example demonstrates the full setup process, including manager initialization, plugin configuration, editor view attachment, and event subscription management.

```javascript
      try {
        manager = await createCollaboration({
          editorId: DOCUMENT_ID,
          veltClient: client,
          schema,
          initialContent: 'Start collaborating in ProseMirror.',
          cursorData: {
            name: 'Ada Lovelace',
            color: '#2563eb',
            colorLight: '#2563eb33',
          },
          autoInitialize: false,
          onError: (error) => console.error('Collaboration error:', error),
        });

        const collaboration = manager.createCollaborationPlugins({
          keymap: {
            'Mod-z': undo,
            'Mod-y': redo,
            'Mod-Shift-z': redo,
            'Mod-b': toggleMark(schema.marks.strong),
            'Mod-i': toggleMark(schema.marks.em),
          },
          plugins: [keymap(baseKeymap)],
        });

        if (collaboration.plugins.length === 0) {
          throw new Error('ProseMirror collaboration plugins were not created');
        }

        const state = EditorState.create({
          schema,
          plugins: collaboration.plugins,
        });

        view = new EditorView(
          document.getElementById('editor')!,
          { state },
        );

        manager.attachEditorView(view);
        await manager.initialize();

        const offStatus = manager.onStatusChange((status) => {
          document.getElementById('status')!.textContent = status;
        });
        const offSynced = manager.onSynced((synced) => {
          document.getElementById('synced')!.textContent = synced ? 'Yes' : 'No';
        });
        const crdtSubscription = client
          .getCrdtElement()
          .on('updateData')
          .subscribe((event) => {
            if (event) console.log('CRDT update:', event);
          });

        const versionId = await manager.saveVersion('Initial collaborative draft');
        console.log('Saved version:', versionId, await manager.getVersions());

        resources = {
          manager,
          view,
          offStatus,
          offSynced,
          crdtSubscription,
        };
      } catch (error) {
        view?.destroy();
        manager?.destroy();
        console.error('Failed to initialize ProseMirror:', error);
      }
    }

    const client = await initVelt('YOUR_VELT_API_KEY');

    await client.identify({
      userId: 'ada',
      name: 'Ada Lovelace',
      email: 'ada@example.com',
      organizationId: 'my-org-id',
    });

    await client.setDocument(DOCUMENT_ID, {
      documentName: 'ProseMirror CRDT Demo',
    });

    let initializationStarted = false;
    const initSubscription = client.getVeltInitState().subscribe((isReady) => {
      if (!isReady || initializationStarted) return;
      initializationStarted = true;
      void initializeProseMirror(client);
    });

    window.addEventListener('beforeunload', () => {
      resources?.crdtSubscription.unsubscribe();
      resources?.offStatus();
      resources?.offSynced();
      initSubscription.unsubscribe();

      resources?.view.destroy();
      resources?.manager.destroy();
    });
```

--------------------------------

### Request Examples for Get Recordings

Source: https://velt.dev/docs/api-reference/rest-apis/v2/recordings/get-recordings

Examples showing how to structure the request body for fetching all recordings, specific IDs, or paginated results.

```JSON
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "recordingIds": ["rec-1", "rec-2"]
  }
}
```

```JSON
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "pageSize": 10,
    "pageToken": "encryptedPageToken"
  }
}
```

--------------------------------

### Full React Integration Example

Source: https://velt.dev/docs/async-collaboration/comments/setup/text

A complete example showing the VeltProvider and VeltComments setup within a React component.

```jsx
import { VeltProvider, VeltComments } from '@veltdev/react';

export default function App() {

  return (
    <VeltProvider apiKey="API_KEY">

      <VeltComments textMode={true} />

    </VeltProvider>
  );
}
```

--------------------------------

### Implement DataProvider get method

Source: https://velt.dev/docs/self-host-data/users

Examples for setting up the user data provider in frontend applications using React/Next.js or other frameworks.

```jsx
const fetchUsersFromDB = async (userIds) => {
  const response = await fetch('/api/velt/users/get', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userIds })
  });
  return await response.json();
};

const userDataProvider = {
  get: fetchUsersFromDB,
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ user: userDataProvider }}
>
</VeltProvider>
```

```js
const fetchUsersFromDB = async (userIds) => {
  const response = await fetch('/api/velt/users/get', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userIds })
  });
  return await response.json();
};

const userDataProvider = {
  get: fetchUsersFromDB,
};

Velt.setDataProviders({ user: userDataProvider });
```

--------------------------------

### Response Example

Source: https://velt.dev/docs/api-reference/rest-apis/v2/agents/config/resolve

A minimal example of a successful configuration resolution response.

```js
{
  "result": {
    "status": "success",
    "message": "Config resolved successfully",
    "data": {
      "resolvedConfig": {
        "extraction_strategies": ["web-page-text"],
        "execution_strategy": "ai",
        "reasoning": "..."
      }
    }
  }
}
```

--------------------------------

### Full React Integration Example

Source: https://velt.dev/docs/async-collaboration/comments/setup/freestyle

Complete implementation example for a React application.

```jsx
import {
  VeltProvider,
  VeltComments,
  VeltCommentTool
} from '@veltdev/react';

export default function App() {

  return (
    <VeltProvider apiKey="API_KEY">
      <VeltComments />

      <div className="toolbar">
        <VeltCommentTool />
      </div>
    </VeltProvider>
  );
}
```

--------------------------------

### Response Examples for Get Recordings

Source: https://velt.dev/docs/api-reference/rest-apis/v2/recordings/get-recordings

Examples of successful and failed API responses.

```JSON
{
  "result": {
    "status": "success",
    "message": "Recorder annotations retrieved successfully.",
    "data": [
      {
        "type": "recorder",
        "recordingType": "screen",
        "mode": "floating",
        "metadata": {
          "apiKey": "YOUR_API_KEY",
          "documentId": "doc-456",
          "organizationId": "org-123"
        },
        "recordedTime": {
          "duration": 4204.55,
          "display": "00:00:04"
        },
        "displayName": "Screen Recording 1773814490242.mp4",
        "annotationId": "ypvmVTROaNU1qP4kq7Cc",
        "attachments": [
          {
            "attachmentId": 875113,
            "url": "https://storage.googleapis.com/...",
            "mimeType": "video/mp4",
            "name": "recording_1773814490242.mp4",
            "type": "mp4",
            "size": 103551
          }
        ],
        "latestVersion": 5
      }
    ],
    "pageToken": "nextPageToken"
  }
}
```

```JSON
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

```js
{
  "result": {
    "status": "success",
    "message": "Recorder annotations retrieved successfully.",
    "data": [
      {
        "type": "recorder",
        "recordingType": "screen",
        "mode": "floating",
        "metadata": {
          "apiKey": "YOUR_API_KEY",
          "documentId": "doc-456",
          "organizationId": "org-123"
        },
        "recordedTime": {
          "duration": 4204.55,
          "display": "00:00:04"
        },
        "displayName": "Screen Recording 1773814490242.mp4",
        "annotationId": "ypvmVTROaNU1qP4kq7Cc",
        "attachments": [
          {
            "attachmentId": 875113,
            "url": "https://storage.googleapis.com/...",
            "mimeType": "video/mp4",
            "name": "recording_1773814490242.mp4",
            "type": "mp4",
            "size": 103551
          }
        ],
        "latestVersion": 5
      }
    ],
    "pageToken": "nextPageToken"
  }
}
```

--------------------------------

### Full Integration Examples

Source: https://velt.dev/docs/async-collaboration/comments/setup/stream

Complete implementation examples for React and standard HTML environments.

```jsx
import { VeltProvider, VeltComments, VeltCommentTool } from '@veltdev/react';

export default function App() {

  return (
    <VeltProvider apiKey="API_KEY">

      <div id="scrolling-container-id">

        //This element is scrollable
        <div className="target-content">
          //This element contains the content that you want to be commented.
        </div>

        <VeltComments
          streamMode={true}
          streamViewContainerId="scrolling-container-id"
        />

      </div>

    </VeltProvider>
  );
}
```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Comment documentation</title>
  </head>
  <body>
    <div id="scrolling-container-id">
      //This element is scrollable
      <div class="target-content">
        //This element contains the content that you want to be commented.
      </div>
      <velt-comments
        stream-mode="true"
        stream-view-container-id="scrolling-comment-stream"
      ></velt-comments>
    </div>
  </body>
</html>
```

--------------------------------

### Get Permissions Request Examples

Source: https://velt.dev/docs/api-reference/rest-apis/v2/auth/get-permissions

Examples of the request body and cURL command required to fetch user permissions.

```json
{
  "data": {
    "organizationId": "org1",
    "documentIds": ["freestyle-comments1"],
    "userIds": ["samarth"]
  }
}
```

```bash
curl --location 'https://api.velt.dev/v2/auth/permissions/get' \
--header 'x-velt-api-key: apiKey' \
--header 'x-velt-auth-token: authToken' \
--header 'Content-Type: application/json' \
--data '{
    "data": {
        "organizationId": "org1",
        "documentIds": [
            "freestyle-comments1"
        ],
        "userIds": [
            "samarth"
        ]
    }
}'
```

--------------------------------

### Install Dependencies

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/spreadjs

Install the required Velt and SpreadJS packages based on your framework.

```bash
npm install @veltdev/spreadjs-crdt-react @veltdev/spreadjs-crdt @veltdev/react @veltdev/types @mescius/spread-sheets react react-dom
```

```bash
npm install @mescius/spread-sheets @veltdev/client @veltdev/spreadjs-crdt
```

--------------------------------

### Full HTML Integration Example

Source: https://velt.dev/docs/async-collaboration/comments/setup/freestyle

Complete implementation example for a standard HTML page.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Comment documentation</title>
  </head>
  <body>
    <velt-comments></velt-comments>

    <div class="toolbar">
      <velt-comment-tool></velt-comment-tool>
    </div>
  </body>
</html>
```

--------------------------------

### Full Implementation Examples

Source: https://velt.dev/docs/permission-management/share-and-invite/customize-ui/slots

Complete component implementation examples for React and standard HTML environments.

```js
import {
  VeltUserInviteTool
} from '@veltdev/react';

export default function App() {

  return (
    <>

      <VeltUserInviteTool>
        <button slot="button">User Invite</button>
      </VeltUserInviteTool>

    </>
  );
}
```

```html
<!doctype html>
<html lang="en">
  <head>
    <title>User Invite documentation</title>
  </head>
  <body>

    <velt-user-invite-tool>
        <button slot="button">User Invite</button>
    </velt-user-invite-tool>

  </body>
</html>
```

--------------------------------

### Install Dependencies

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/blocknote

Install the necessary Velt, BlockNote, and Yjs packages for your environment.

```bash
npm install @veltdev/blocknote-crdt-react @veltdev/blocknote-crdt @veltdev/react @veltdev/types @blocknote/core @blocknote/react @blocknote/mantine yjs
```

```bash
npm install @veltdev/blocknote-crdt @veltdev/client @blocknote/core yjs
```

--------------------------------

### Install Dependencies

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/codemirror

Install the necessary Velt and CodeMirror packages for your project environment.

```bash
npm install @veltdev/codemirror-crdt-react @veltdev/codemirror-crdt @veltdev/react @veltdev/types codemirror @codemirror/state @codemirror/view y-codemirror.next yjs
```

```bash
npm install @veltdev/codemirror-crdt @veltdev/client codemirror @codemirror/state y-codemirror.next yjs
```

--------------------------------

### Setup Velt Comments with Chart.js

Source: https://velt.dev/docs/async-collaboration/comments/setup/chart-comments-setup/chartjs

This example shows how to register Chart.js components, manage chart state, and render Velt comment pins based on chart data points.

```javascript
import React, { useEffect, useRef, useMemo } from 'react';
import { Chart as ChartJS, CategoryScale, LinearScale, PointElement, BarElement, Title, Tooltip, Legend, Filler,} from 'chart.js';
import { Bar } from 'react-chartjs-2';
import { useVeltClient, useCommentAnnotations, useCommentModeState, VeltCommentPin } from '@veltdev/react';

// Register the necessary Chart.js components
ChartJS.register(CategoryScale, LinearScale, PointElement, BarElement, Title, Tooltip, Legend, Filler);

// Define the data for the chart
const scores = [6, 5, 5, 5, 3, 4, 6, 4, 5];
const labels = [100, 200, 300, 400, 500, 600, 700];

// Set the options for the chart
const options: any = {
// your chart options
};

const BarChart = () => {
  const chartId = 'dataAnalyticsChart'; // Unique ID for the chart
  const chartRef = useRef(null); // Reference to the chart instance
  const { client } = useVeltClient(); // Get Velt client
  const commentModeState = useCommentModeState(); // Get Velt comment mode state
  const commentAnnotations = useCommentAnnotations(); // Get Velt comment annotations
  const [chartCommentAnnotations, setChartCommentAnnotations] = React.useState([]); // State for chart comments

  // Update chart comments when annotations change
  useEffect(() => {
    // Filter comments for the current chart, using unique chart ID
    const chartCommentAnnotations = commentAnnotations?.filter((comment) => comment.context?.chartId === chartId); 
    setChartCommentAnnotations(chartCommentAnnotations as any || []);
  }, [commentAnnotations]);

  // Handle chart clicks to find nearest data point and add a comment
  const handleChartClick = (event: any) => {
    const chart: any = chartRef.current;
    if (chart) {
      // Get the nearest element to the click event
      const elements = chart.getElementsAtEventForMode(event.nativeEvent, 'nearest', { intersect: true }, false);
      if (elements.length > 0) {
        const element = elements[0];
        const datasetIndex = element.datasetIndex;
        const index = element.index;
        const dataset = chart.data.datasets[datasetIndex];
        const xValue = chart.data.labels[index];
        const yValue = dataset.data[index];
        const context = { seriesId: dataset.label, xValue, yValue, chartId };
        addManualComment(context); // Add a comment at the nearest data point with the context data
      }
    }
  };

  // Add a manual comment to the chart
  const addManualComment = (context: any) => {
    try {
      if (client && commentModeState) {
        const commentElement = client.getCommentElement();
        commentElement.addManualComment({ context }); // Add a Velt comment
      }
    } catch (error) {
      console.error('Error adding manual comment', error);
    }
  };

  // Find the exact point on the chart to place a comment pin
  const findPoint = (seriesId: any, xValue: any, yValue: any) => {
    const chart: any = chartRef.current;
    if (chart) {
      const dataset = chart.data.datasets.find((dataset: any) => dataset.label === seriesId);
      const index = chart.data.labels.indexOf(xValue);
      if (dataset && index !== -1) {
        const yValueInDataset = dataset.data[index];
        if (yValueInDataset === yValue) {
          return { x: chart.scales.x.getPixelForValue(index), y: chart.scales.y.getPixelForValue(yValue) }; // Set the x, y position for the comment pin
        }
      }
    }
    return null;
  };

  // Show the comment pin on the chart at the specified point
  const showCommentPin = (commentAnnotation: any) => {
    const context = commentAnnotation.context || {};
    const point = findPoint(context.seriesId, context.xValue, context.yValue);
    if (point) {
      const { x, y } = point;
      return (
        <div
          key={commentAnnotation.annotationId}
          style={{
            left: `${x}px`,
            top: `${y}px`,
            position: 'absolute',
            transform: 'translate(0%, -100%)',
            zIndex: 1000,
          }}
        >
          <VeltCommentPin annotationId={commentAnnotation.annotationId} /> {/* Velt comment pin component */}
        </div>
      );
    }
    return null;
  };

  // Memoize the chart data
  const data = useMemo(() => {
    return {
      datasets: [
        {
          label: 'Mis datos',
          tension: 0.3,
          data: scores,
          borderColor: 'rgb(75, 192, 192)',
          backgroundColor: 'rgba(75, 192, 192, 0.3)',
        },
      ],
      labels,
    };
  }, []);
```

--------------------------------

### View Analytics Implementation Examples

Source: https://velt.dev/docs/async-collaboration/view-analytics/setup

Complete implementation examples for React/Next.js and standard HTML environments.

```js
import { VeltViewAnalytics } from '@veltdev/react';

function YourComponent() {

  return (
    <div className="toolbar">
      <VeltViewAnalytics />
    </div>
  )
  
}
```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Collaboration App</title>
    <script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
    <script>
      async function loadVelt() {
        await Velt.init("YOUR_VELT_API_KEY");
      }
    </script>
  </head>
  <body>
    <div className="toolbar">
      <velt-view-analytics></velt-view-analytics>
    </div>
    
  </body>
</html>
```

--------------------------------

### Activity Config Response Examples

Source: https://velt.dev/docs/api-reference/rest-apis/v2/workspace/activityconfig-update

Examples of successful and failed API responses.

```JSON
{
  "result": {
    "status": "success",
    "message": "Activity logs configuration updated successfully.",
    "data": {
      "activityServiceConfig": {
        "isEnabled": true,
        "immutable": false,
        "enabledTime": 1717520000000
      }
    }
  }
}
```

```JSON
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "message": "At least one field must be provided for update"
  }
}
```

```js
{
  "result": {
    "status": "success",
    "message": "Activity logs configuration updated successfully.",
    "data": {
      "activityServiceConfig": {
        "isEnabled": true,
        "immutable": false,
        "enabledTime": 1717520000000
      }
    }
  }
}
```

--------------------------------

### Complete Huddle Implementation Examples

Source: https://velt.dev/docs/realtime-collaboration/huddle/setup

Full implementation examples for React and standard HTML environments.

```js
import { VeltHuddle, VeltHuddleTool} from '@veltdev/react';

export default function App() {

  return (
    <VeltHuddle /> {/* Add VeltHuddle at the root of your app */}

    <div className="toolbar">
      <VeltHuddleTool type='all' /> {/* Add VeltHuddleTool where you want the huddle button to appear */}
    </div>
  );
}
```

```html
<div>
  <velt-huddle></velt-huddle> <!-- Add velt-huddle component at the root of your app -->
  <velt-huddle-tool></velt-huddle-tool> <!-- Add velt-huddle-tool where you want the huddle button to appear-->
</div>
```

--------------------------------

### React Integration Example

Source: https://velt.dev/docs/realtime-collaboration/cursors/setup

Complete example of integrating VeltProvider and VeltCursor in a React application.

```js
import { VeltProvider, VeltCursor } from '@veltdev/react';

export default function App() {

  return (
    <VeltProvider apiKey="API_KEY">
      <VeltCursor />
      {/* ... */}
    </VeltProvider>
  );
}
```

--------------------------------

### Full Implementation Example

Source: https://velt.dev/docs/async-collaboration/comments/standalone-components/comment-thread/setup

Complete examples for integrating comment threads in React and other frameworks.

```jsx
import { VeltCommentThread, useCommentAnnotations } from '@veltdev/react';

export default function YourDocument() {

  let commentAnnotations = useCommentAnnotations()

  return (
    <div>
      {commentAnnotations.map((x,i) => <VeltCommentThread key={i} annotationId={x.annotationId}/>)}
    </div>
  )
}
```

```js
const commentElement = client.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((comments) => {
    // If you are using pure html, inject <velt-comment-thread annotation-id="ANNOTATION_ID"></velt-comment-thread>
    // In other frameworks, you can loop over the comments inside the template itself
});

//To unsubscribe from the subscription:
subscription?.unsubscribe()
```

--------------------------------

### Install and Configure Cursor Plugin

Source: https://velt.dev/docs/get-started/ui-customization-plugin

Commands to clone, install, and configure the Velt Figma plugin for Cursor.

```bash
git clone https://github.com/velt-js/velt-figma-plugin-cursor.git
cd velt-figma-plugin-cursor
npm run all
```

```bash
node scripts/figma-extract.mjs token set
```

```bash
npm i -g playwright-core
```

```text
/velt-customize-run <figma-loop-node-url> <app-url> --mode "wireframes + primitives" --budget balanced
```

--------------------------------

### Install Dependencies

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/ace

Install the required Velt CRDT and Ace Editor packages based on your framework.

```bash
npm install @veltdev/ace-crdt-react @veltdev/ace-crdt react-ace ace-builds @veltdev/react @veltdev/types react react-dom
```

```bash
npm install @veltdev/ace-crdt ace-builds @veltdev/client @veltdev/crdt @veltdev/types yjs y-protocols
```

--------------------------------

### HTML Integration Example

Source: https://velt.dev/docs/realtime-collaboration/cursors/setup

Complete example of integrating the velt-cursor component in a standard HTML file.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Cursors documentation</title>
  </head>
  <body>
    <velt-cursor></velt-cursor>
  </body>
</html>
```

--------------------------------

### Full HTML Implementation Example

Source: https://velt.dev/docs/in-app-user-feedback/setup

A complete HTML document showing the SDK initialization and component placement.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Collaboration App</title>
    <script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
    <script>
      async function loadVelt() {
        await Velt.init("YOUR_VELT_API_KEY");
      }
    </script>
  </head>
  <body>
    <!-- Place the <velt-user-request-tool> component -->
    <div class="toolbar">
      <velt-user-request-tool></velt-user-request-tool>
    </div>
  </body>
</html>
```

--------------------------------

### Example Response for Get Agent Group

Source: https://velt.dev/docs/api-reference/rest-apis/v2/agents/groups/get

An alternative example of a successful response structure.

```JavaScript
{
  "result": {
    "status": "success",
    "message": "Agent group fetched successfully",
    "data": {
      "group": {
        "id": "K3mR7pQxN2vB9wLdT4sY",
        "name": "Brand QA",
        "agentIds": ["abc123def456"],
        "metadata": { "apiKey": "ak_xxx" },
        "createdAt": 1711900000000,
        "updatedAt": 1711900000000
      }
    }
  }
}
```

--------------------------------

### Complete HTML Setup

Source: https://velt.dev/docs/get-started/quickstart

A full HTML implementation including SDK initialization, user identification, document setting, and UI components.

```html
<!DOCTYPE html>
      <html lang="en">
      <head>
        <meta charset="UTF-8">
        <title>My Collaborative App</title>
        <script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
        <script>
          async function loadVelt() {
            await Velt.init("YOUR_VELT_API_KEY");

            // Authenticate user
            const user = {
              userId: "user123",
              organizationId: "org123",
              name: "John Doe",
              email: "john@example.com",
              photoUrl: "https://i.pravatar.cc/300",
              color: "#FF6B6B",
              textColor: "#FFFFFF"
            };
            await Velt.identify(user);

            // Set document
            await Velt.setDocument('my-document-id', { documentName: 'My Document' });
          }
        </script>
      </head>
      <body>
        <h1>My Collaborative App</h1>
        <velt-comments></velt-comments>
        <velt-presence></velt-presence>
        <velt-comment-tool></velt-comment-tool>
        <!-- Your app content -->
      </body>
      </html>
```

--------------------------------

### Get Execution Responses

Source: https://velt.dev/docs/api-reference/rest-apis/v2/approval-engine/executions/get-execution

Examples of successful and failed API responses for the Get Execution endpoint.

```JSON
{
  "result": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "status": "completed",
    "startedAt": 1777374504364,
    "completedAt": 1777374842347,
    "cancelledAt": null,
    "definitionId": "marketing-copy-approval",
    "definitionVersion": 1,
    "correlationId": "corr_campaign_42",
    "idempotencyKey": "campaign-42-dispatch",
    "failureReason": null,
    "steps": [
      {
        "stepId": "group_parallel-review__to__agent-publish",
        "nodeId": "agent-publish",
        "nodeType": "agent",
        "status": "completed",
        "groupId": null,
        "startedAt": 1777374841756,
        "completedAt": 1777374841986,
        "output": {
          "agentId": "publish-agent-v1",
          "summary": "...",
          "generatedAt": 1777374841939
        },
        "error": null
      }
    ]
  }
}
```

```JSON
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "NOT_FOUND"
  }
}
```

```js
{
  "result": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "status": "completed",
    "startedAt": 1777374504364,
    "completedAt": 1777374842347,
    "cancelledAt": null,
    "definitionId": "marketing-copy-approval",
    "definitionVersion": 1,
    "correlationId": "corr_campaign_42",
    "idempotencyKey": "campaign-42-dispatch",
    "failureReason": null,
    "steps": []
  }
}
```

--------------------------------

### Initialize Velt SDK with Full Configuration

Source: https://velt.dev/docs/backend-sdks/python

Complete configuration example including database, AWS, collections, user schema, and API keys.

```python
from velt_py import VeltSDK

config = {
    'database': {
        'connection_string': 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',
    },
    'aws': {
        'bucket_name': 'your-bucket-name',
        'region': 'us-east-1',
        'access_key_id': 'YOUR_AWS_ACCESS_KEY',
        'secret_access_key': 'YOUR_AWS_SECRET_KEY'
    },
    'collections': {
        'comments': 'comment_annotations',
        'reactions': 'reaction_annotations',
        'attachments': 'attachments',
        'users': 'users'
    },
    'user_schema': {
        'userId': 'userId',
        'name': 'name',
        'photoUrl': 'photoUrl',
        'email': 'email',
        'color': 'color',
        'textColor': 'textColor',
        'isAdmin': 'isAdmin',
        'initial': 'initial'
    },
    'apiKey': 'YOUR_VELT_API_KEY',
    'authToken': 'YOUR_VELT_AUTH_TOKEN'
}

sdk = VeltSDK.initialize(config)
```

--------------------------------

### Install Velt Node.js SDK

Source: https://velt.dev/docs/backend-sdks/node

Install the core Velt SDK package via npm.

```bash
npm install @veltdev/node
```

--------------------------------

### Get Notifications Config Request Examples

Source: https://velt.dev/docs/api-reference/rest-apis/v2/notifications/get-config

Examples of request bodies for fetching document-level or organization-level notification configurations.

```JSON
{
    "data": {
        "organizationId": "org1",
        "documentIds": ["doc1"],
        "userId":"USER_ID1"
    }
}
```

```JSON
{
    "data": {
        "organizationId": "org1",
        "userId": "USER_ID1",
        "getOrganizationConfig": true
    }
}
```

--------------------------------

### Full HTML Implementation Example

Source: https://velt.dev/docs/async-collaboration/comments/setup/page

A complete example showing the initialization of the Velt SDK and the placement of components in a standard HTML file.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Collaboration App</title>
    <script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
    <script>
      async function loadVelt() {
        await Velt.init("YOUR_VELT_API_KEY");
      }
    </script>
  </head>
  <body>
    <velt-comments></velt-comments> <!-- add to the root of your app-->
    <velt-comments-sidebar page-mode="true"></velt-comments-sidebar> <!-- add to the root of your app -->
    <div class="toolbar"> <!-- a component representing a toolbar-->
      <velt-sidebar-button></velt-sidebar-button> <!-- add wherever you want it to appear -->
    </div>
    

  </body>
</html>
```

--------------------------------

### Complete Velt SDK Configuration

Source: https://velt.dev/docs/backend-sdks/node

Full initialization example including database, credentials, and a graceful shutdown handler.

```ts
import { VeltSDK } from '@veltdev/node';

const sdk = VeltSDK.initialize({
  database: {
    host: 'localhost:27017',
    username: 'your-username',
    password: 'your-password',
    auth_database: 'admin',
    database_name: 'velt-db',
  },
  apiKey: 'YOUR_VELT_API_KEY',
  authToken: 'YOUR_VELT_AUTH_TOKEN'
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  await sdk.close();
  process.exit(0);
});
```

--------------------------------

### Get documents request examples

Source: https://velt.dev/docs/api-reference/rest-apis/v2/documents/get-documents-v2

Examples of JSON request bodies for fetching documents by organization, specific IDs, or folder ID.

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentIds": ["yourDocumentId1", "yourDocumentId2"]
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId"
  }
}
```

--------------------------------

### Comment Annotations Response Structure

Source: https://velt.dev/docs/api-reference/rest-apis/comments-feature/comment-annotations/get-comment-annotations-v2

Example JSON response structure for the get comment annotations endpoint.

```json
{
    "result": {
        "status": "success",
        "message": "Annotations fetched successfully.",
        "data": {
            "documentId1": [
                {
                    "annotationId": "annotationId1",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
                {
                    "annotationId": "annotationId2",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
            ],
            "documentId1": [
                {
                    "annotationId": "annotationId1",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
                {
                    "annotationId": "annotationId2",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
            ]
        },
        "nextPageToken": "Ds7NMZw0wWSdmfJFLNioTw=="
    }
}
```

--------------------------------

### Simple HTML Setup

Source: https://velt.dev/docs/get-started/quickstart

A minimal HTML implementation that initializes the Velt SDK and adds a comments component.

```html
<!DOCTYPE html>
      <html lang="en">
      <head>
        <meta charset="UTF-8">
        <title>My Collaborative App</title>
        <script type="module" src="https://cdn.velt.dev/lib/sdk@latest/velt.js" onload="loadVelt()"></script>
        <script>
          async function loadVelt() {
            await Velt.init("YOUR_VELT_API_KEY");
          }
        </script>
      </head>
      <body>
        <h1>My Collaborative App</h1>
        <velt-comments></velt-comments>
        <!-- Your app content -->
      </body>
      </html>
```

--------------------------------

### Get CRDT Data Error Response

Source: https://velt.dev/docs/api-reference/rest-apis/v2/crdt/get-crdt-data

Example error response returned when required parameters are missing.

```JSON
{
  "error": {
    "message": "Organization ID is required",
    "status": "INVALID_ARGUMENT"
  }
}
```

--------------------------------

### Create Workbook Host and Instance

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/spreadjs

Define the HTML host element, apply the license key, and initialize the workbook instance.

```html
<div id="spread-host" class="spread-host"></div>
```

```typescript
import GC from '@mescius/spread-sheets';

GC.Spread.Sheets.LicenseKey = 'YOUR_SPREADJS_LICENSE_KEY';

const host = document.querySelector<HTMLDivElement>('#spread-host')!;
const workbook = new GC.Spread.Sheets.Workbook(host, {
  sheetCount: 2,
  tabEditable: true,
});
```

```css
.spread-host {
  height: 640px;
  min-height: 480px;
  position: relative;
  width: 100%;
}
```

--------------------------------

### Get CRDT Data Request

Source: https://velt.dev/docs/api-reference/rest-apis/v2/crdt/get-crdt-data

Example request body for retrieving CRDT data from a specific document and editor instance.

```JSON
{
  "data": {
    "organizationId": "YOUR_ORGANIZATION_ID",
    "documentId": "YOUR_DOCUMENT_ID",
    "editorId": "my-collab-note"
  }
}
```

--------------------------------

### Get Notifications Request Examples

Source: https://velt.dev/docs/api-reference/rest-apis/v2/notifications/get-notifications-v2

Various JSON request body configurations for retrieving notifications based on different filtering criteria.

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "notificationIds": [
      "yourNotificationId"
    ]
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationId": "yourLocationId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationId": "yourLocationId",
    "notificationIds": [
      "yourNotificationId"
    ]
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "userId": "yourUserId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "userId": "yourUserId",
    "notificationIds": [
      "yourNotificationId"
    ]
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "userId": "yourUserId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "userId": "yourUserId",
    "locationId": "yourLocationId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

```JSON
{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "userId": "yourUserId",
    "locationId": "yourLocationId",
    "pageSize": 20,
    "pageToken": "8740648311207869"
  }
}
```

--------------------------------

### Implement inline comments in React and HTML

Source: https://velt.dev/docs/async-collaboration/comments/setup/inline-comments

Basic setup examples for integrating Velt inline comments into React/Next.js applications and standard HTML pages.

```jsx
import { VeltProvider, VeltComments } from '@veltdev/react';

export default function App() {

  return (
    <VeltProvider apiKey="API_KEY">

      <VeltComments />

      <section id="container-id">
        <div>Your Article</div>

        <VeltInlineCommentsSection
          targetElementId="container-id"
          shadowDom={false}
          dialogVariant="dialog-variant"
          variant="inline-section-variant"
          darkMode={true}
        />
      </section>


    </VeltProvider>
  );
}
```

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Comment documentation</title>
  </head>
  <body>
    <velt-comments></velt-comments>
    <section id="container-id">
      <div>Your Article</div>

      <velt-inline-comments-section
        target-element-id="container-id"
        shadow-dom="false"
        dialog-variant="dialog-variant"
        variant="inline-section-variant"
        dark-mode="true"
      >
      </velt-inline-comments-section>
    </section>

  </body>
</html>
```

--------------------------------

### Complete endpoint configuration example

Source: https://velt.dev/docs/self-host-data/notifications

A comprehensive example including both fetch and delete endpoints, along with timeout and retry configurations.

```jsx
const notificationDataProvider = {
  config: {
    getConfig: {
      url: 'https://your-backend.com/api/velt/notifications/get',
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    },
    deleteConfig: {
      url: 'https://your-backend.com/api/velt/notifications/delete',
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    },
    resolveTimeout: 5000,
    getRetryConfig: { retryCount: 3, retryDelay: 2000 },
    deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
  },
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ notification: notificationDataProvider }}
>
</VeltProvider>
```

```js
const notificationDataProvider = {
  config: {
    getConfig: {
      url: 'https://your-backend.com/api/velt/notifications/get',
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    },
    deleteConfig: {
      url: 'https://your-backend.com/api/velt/notifications/delete',
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    },
    resolveTimeout: 5000,
    getRetryConfig: { retryCount: 3, retryDelay: 2000 },
    deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
  },
};

Velt.setDataProviders({ notification: notificationDataProvider });
```

--------------------------------

### Install Velt MCP globally

Source: https://velt.dev/docs/get-started/mcp-installer

Use this command to install the Velt MCP installer package globally on your system.

```bash
npm install -g @velt-js/mcp-installer
```

--------------------------------

### HTML Integration Example

Source: https://velt.dev/docs/realtime-collaboration/flock-mode/setup

Standard HTML implementation for enabling Follow Me mode.

```html
<velt-presence flock-mode="true"></velt-presence> <!-- Enable Follow Me Mode -->
```

--------------------------------

### Velt User Request Tool Implementation Examples

Source: https://velt.dev/docs/in-app-user-feedback/customize-behavior

Full implementation examples for React and HTML showing all available modes.

```js
import { VeltUserRequestTool } from '@veltdev/react';

function YourComponent() {

  return (
		<div>
      <VeltUserRequestTool /> {/* Feedback Mode */} 
      <VeltUserRequestTool type="reportBug"/>  {/* Report Bug Mode */} 
      <VeltUserRequestTool type="contactUs"/>  {/* Contact Us Mode */} 
    </div>
  )
}
```

```html
<velt-user-request-tool></velt-user-request-tool> <!-- Feedback Mode -->
<velt-user-request-tool type="reportBug"></velt-user-request-tool> <!-- Report Bug Mode-->
<velt-user-request-tool type="contactUs"></velt-user-request-tool> <!-- Contact Us Mode-->
```

--------------------------------

### Install Velt SDK Dependencies

Source: https://velt.dev/docs/get-started/quickstart

Install the required Velt SDK package for your specific framework. Optional type definitions can be installed for improved development experience.

```bash
npm install @veltdev/react
# Optional: npm install --save-dev @veltdev/types
```

```bash
npm install @veltdev/client
# Optional: npm install --save-dev @veltdev/types
```

```bash
npm install @veltdev/client
# Optional: npm install --save-dev @veltdev/types
```

--------------------------------

### Response Example

Source: https://velt.dev/docs/api-reference/rest-apis/v2/workspace/email-status

Example response structure for a successful verification.

```js
{
  "result": {
    "status": "success",
    "message": "Email verified and workspace reactivated",
    "data": {
      "verified": true
    }
  }
}
```

--------------------------------

### Replace store creation logic

Source: https://velt.dev/docs/realtime-collaboration/crdt/setup/codemirror

Transition from the callback-based extension creation to the async manager-based initialization.

```js
// Before (v1)
import { createVeltCodeMirrorCrdtExtension } from '@veltdev/codemirror-crdt';
const cleanup = createVeltCodeMirrorCrdtExtension(
  { editorId: 'my-doc', veltClient: client },
  ({ store }) => {
    const state = EditorState.create({
      doc: store.getYText()?.toString() ?? '',
      extensions: [basicSetup, yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() })],
    });
    new EditorView({ state, parent: document.querySelector('#editor') });
  }
);

// After (v2)
import { createCollaboration } from '@veltdev/codemirror-crdt';
const manager = await createCollaboration({ editorId: 'my-doc', veltClient: client });
const { ytext, awareness, undoManager } = manager.getCollaborationPrimitives();
const state = EditorState.create({
  doc: ytext.toString(),
  extensions: [basicSetup, yCollab(ytext, awareness, { undoManager })],
});
new EditorView({ state, parent: document.querySelector('#editor') });
```

--------------------------------

### Response Example

Source: https://velt.dev/docs/api-reference/rest-apis/v2/agents/prompt/refine

A simplified example of the success response structure.

```js
{
  "result": {
    "status": "success",
    "message": "Prompt refined successfully",
    "data": {
      "refinerResult": {
        "analysis_prompt": "## Objective\n...\n\n## Detection Logic\n...",
        "response_descriptions": {}
      }
    }
  }
}
```

--------------------------------

### Full HTML implementation example

Source: https://velt.dev/docs/async-collaboration/comments/setup/video-player-setup/video-player-setup

Complete HTML document structure demonstrating the usage of the velt-video-player custom element.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Video Player documentation</title>
  </head>
  <body>
    <!-- dark-mode="false" - to disable dark mode -->
    <!-- sync="true" - to enable sync mode -->
    <velt-video-player 
        src="http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/Sintel.mp4"
        dark-mode="false"
        sync="true"
    >
    </velt-video-player>
  </body>
</html>
```
Tokens:
Raw