Python - Velt

Overview

The Velt Python SDK exposes two independent backends:

Backend	Namespace	Use case
Self-hosting	`sdk.selfHosting.*`	Store Velt data in your own MongoDB + AWS S3
REST API	`sdk.api.*`	Call Velt’s REST APIs directly — no database required

Self-hosting backend (sdk.selfHosting.*) simplifies backend implementation by 90%. Instead of writing custom database queries and storage logic, you:

Pass your DB and storage configs to the SDK
Pass the raw request object directly to SDK methods
Return the resulting response object straight to the client

REST API backend (sdk.api.*) — new in v0.1.9 — provides feature parity with the Velt Node SDK. 17 services, typed @dataclass request objects, and raw Velt API responses. No database or AWS configuration needed.

Installation

pip install velt-py

Requirements

Python 3.8+
Django 4.2.26+ (only if using the self-hosting backend)
MongoDB (Percona Server or MongoDB Atlas) for self-hosting
requests for REST API calls (installed automatically)

Quick Start

Initialize the SDK

Self-hosting initialization (MongoDB + optional AWS):

from velt_py import VeltSDK

# Initialize with database and AWS config
config = {
    'database': {
        # Option 1: Connection string (recommended for MongoDB Atlas)
        'connection_string': 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',
        
        # Option 2: Individual components
        # 'host': 'localhost:27017',
        # 'username': 'your_username',
        # 'password': 'your_password',
        # 'auth_database': 'admin',
        # 'database_name': 'velt-db'
    },
    # Optional: AWS S3 config for attachments
    'aws': {
        'bucket_name': 'your-bucket',
        'region': 'us-east-1',
        'access_key_id': 'YOUR_ACCESS_KEY',
        'secret_access_key': 'YOUR_SECRET_KEY'
    },
    # Optional: Custom collection names
    'collections': {
        'comments': 'comment_annotations',
        'reactions': 'reaction_annotations',
        'attachments': 'attachments',
        'users': 'users'
    },
    # Required for token generation; also enables sdk.api.*
    'apiKey': 'YOUR_VELT_API_KEY',
    'authToken': 'YOUR_VELT_AUTH_TOKEN'
}

sdk = VeltSDK.initialize(config)

REST API-only initialization (no database needed — new in v0.1.9):

from velt_py import VeltSDK

# Minimal config for REST API backend only
config = {
    'apiKey': 'YOUR_VELT_API_KEY',
    'authToken': 'YOUR_VELT_AUTH_TOKEN'
}

sdk = VeltSDK.initialize(config)

# All sdk.api.* services are now available
result = sdk.api.organizations.getOrganizations(...)

The database section is optional when using only sdk.api.*. Set VELT_API_KEY and VELT_AUTH_TOKEN environment variables as an alternative to passing credentials in the config dict.

Configuration

Environment Variables

The SDK reads the following environment variables automatically. These can be used instead of (or in addition to) config dict keys.

Variable	Config key equivalent	Purpose
`VELT_API_KEY`	`apiKey`	Velt API key for authenticating REST API calls
`VELT_AUTH_TOKEN`	`authToken`	Velt auth token for authenticating REST API calls
`VELT_WORKSPACE_ID`	—	Default workspace ID for workspace-scoped operations
`VELT_WORKSPACE_AUTH_TOKEN`	—	Auth token scoped to a specific workspace

Self-Hosting Configuration

Database
AWS (Attachments)
Collections
User Schema
Complete Example

Configure MongoDB connection for storing comments, reactions, and user data.

config = {
    'database': {
        # Option 1: Connection string (recommended for MongoDB Atlas)
        'connection_string': 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',
        
        # Option 2: Individual components (for local MongoDB or custom setup)
        # 'host': 'localhost:27017',
        # 'username': 'your_username',
        # 'password': 'your_password',
        # 'auth_database': 'admin',
        # 'database_name': 'velt-db'
    }
}

Configure AWS S3 for storing file attachments.

config = {
    'aws': {
        'bucket_name': 'your-bucket-name',
        'region': 'us-east-1',
        'access_key_id': 'YOUR_AWS_ACCESS_KEY',
        'secret_access_key': 'YOUR_AWS_SECRET_KEY'
    }
}

Customize collection names for storing Velt data.

config = {
    'collections': {
        'comments': 'comment_annotations',    # Default: 'comment_annotations'
        'reactions': 'reaction_annotations',  # Default: 'reaction_annotations'
        'attachments': 'attachments',         # Default: 'attachments'
        'users': 'users'                      # Default: 'users'
    }
}

Map your user schema fields to Velt’s expected fields if your database uses different field names.

config = {
    'user_schema': {
        'userId': 'userId',       # Your field name for user ID
        'name': 'name',           # Your field name for display name
        'photoUrl': 'photoUrl',   # Your field name for avatar URL
        'email': 'email',         # Your field name for email
        'color': 'color',         # Your field name for user color
        'textColor': 'textColor', # Your field name for text color
        'isAdmin': 'isAdmin',     # Your field name for admin flag
        'initial': 'initial'      # Your field name for user initial
    }
}

Full configuration with database, AWS, collections, and user schema.

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)

Self-Hosting Backend

The SDK provides methods that accept the raw request from the frontend and return the properly formatted response.

Comments

`getComments`

Fetches comments from your database for a document.
Params: GetCommentResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import GetCommentResolverRequest

def get_comments(request):
    data = request.json
    comment_request = GetCommentResolverRequest.from_dict(data)
    result = sdk.selfHosting.comments.getComments(comment_request)
    return result

Response

{
    'success': True,
    'statusCode': 200,
    'data': { 'comments': [ ... ] }
}

`saveComments`

Saves new or updated comments to your database.
Params: SaveCommentResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import SaveCommentResolverRequest

def save_comments(request):
    data = request.json
    save_request = SaveCommentResolverRequest.from_dict(data)
    result = sdk.selfHosting.comments.saveComments(save_request)
    return result

Response

{ 'success': True, 'statusCode': 200, 'data': { ... } }

`deleteComment`

Deletes a comment from your database.
Params: DeleteCommentResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import DeleteCommentResolverRequest

def delete_comment(request):
    data = request.json
    delete_request = DeleteCommentResolverRequest.from_dict(data)
    result = sdk.selfHosting.comments.deleteComment(delete_request)
    return result

Response

{ 'success': True, 'statusCode': 200, 'data': { ... } }

Reactions

`getReactions`

Fetches reactions from your database for a document.
Params: GetReactionResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import GetReactionResolverRequest

def get_reactions(request):
    data = request.json
    reaction_request = GetReactionResolverRequest.from_dict(data)
    result = sdk.selfHosting.reactions.getReactions(reaction_request)
    return result

Response

{
    'success': True,
    'statusCode': 200,
    'data': { 'reactions': [ ... ] }
}

`saveReactions`

Saves new or updated reactions to your database.
Params: SaveReactionResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import SaveReactionResolverRequest

def save_reactions(request):
    data = request.json
    save_request = SaveReactionResolverRequest.from_dict(data)
    result = sdk.selfHosting.reactions.saveReactions(save_request)
    return result

Response

{ 'success': True, 'statusCode': 200, 'data': { ... } }

`deleteReaction`

Deletes a reaction from your database.
Params: DeleteReactionResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import DeleteReactionResolverRequest

def delete_reaction(request):
    data = request.json
    delete_request = DeleteReactionResolverRequest.from_dict(data)
    result = sdk.selfHosting.reactions.deleteReaction(delete_request)
    return result

Response

{ 'success': True, 'statusCode': 200, 'data': { ... } }

Users

`getUsers`

Fetches users from your database.
Params: GetUserResolverRequest
Returns: VeltSelfHostingResponse

from velt_py import GetUserResolverRequest

def get_users(request):
    data = request.json
    user_request = GetUserResolverRequest.from_dict(data)
    result = sdk.selfHosting.users.getUsers(user_request)
    return result

Response

{
    'success': True,
    'statusCode': 200,
    'data': { 'users': [ { 'userId': 'user-1', 'name': 'John Doe', ... } ] }
}

Attachments

`saveAttachment`

Uploads an attachment file to S3 and saves the metadata.
Params: SaveAttachmentResolverRequest
Returns: VeltSelfHostingResponse

Django
Flask
FastAPI

import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from velt_py import SaveAttachmentResolverRequest, DeleteAttachmentResolverRequest
from .velt_sdk import get_velt_sdk

@csrf_exempt
@require_http_methods(["POST"])
def save_attachment(request):
    try:
        file = request.FILES.get('file')
        request_json_str = request.POST.get('request')
        
        if not file or not request_json_str:
            return JsonResponse({
                'success': False,
                'error': 'File and request JSON are required',
                'errorCode': 'INVALID_INPUT',
                'statusCode': 400
            }, status=400)
        
        request_data = json.loads(request_json_str)
        save_request = SaveAttachmentResolverRequest.from_dict(request_data)
        
        sdk = get_velt_sdk()
        result = sdk.selfHosting.attachments.saveAttachment(
            save_request,
            file_data=file.read(),
            file_name=file.name,
            mime_type=file.content_type
        )
        return JsonResponse(result, status=result.get('statusCode', 200))
    except Exception as e:
        return JsonResponse({
            'success': False,
            'error': str(e),
            'errorCode': 'INTERNAL_ERROR',
            'statusCode': 500
        }, status=500)

import json
from flask import request, jsonify
from velt_py import SaveAttachmentResolverRequest

@app.route('/api/velt/attachments/save', methods=['POST'])
def save_attachment():
    try:
        file = request.files.get('file')
        request_json = request.form.get('request')
        
        if not file or not request_json:
            return jsonify({
                'success': False,
                'error': 'File and request JSON are required',
                'errorCode': 'INVALID_INPUT',
                'statusCode': 400
            }), 400
        
        request_data = json.loads(request_json)
        save_request = SaveAttachmentResolverRequest.from_dict(request_data)
        
        result = sdk.selfHosting.attachments.saveAttachment(
            save_request,
            file_data=file.read(),
            file_name=file.filename,
            mime_type=file.content_type
        )
        return jsonify(result), result.get('statusCode', 200)
    except Exception as e:
        return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500

import json
from fastapi import Request, UploadFile, File, Form
from fastapi.responses import JSONResponse
from velt_py import SaveAttachmentResolverRequest

@app.post('/api/velt/attachments/save')
async def save_attachment(file: UploadFile = File(...), request: str = Form(...)):
    try:
        request_data = json.loads(request)
        save_request = SaveAttachmentResolverRequest.from_dict(request_data)
        
        file_bytes = await file.read()
        result = sdk.selfHosting.attachments.saveAttachment(
            save_request,
            file_data=file_bytes,
            file_name=file.filename,
            mime_type=file.content_type
        )
        return JSONResponse(content=result, status_code=result.get('statusCode', 200))
    except Exception as e:
        return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)

Response

{ 'success': True, 'statusCode': 200, 'data': { ... } }

`deleteAttachment`

Deletes an attachment file from S3 and removes its metadata.
Params: DeleteAttachmentResolverRequest
Returns: VeltSelfHostingResponse

Django
Flask
FastAPI

import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from velt_py import DeleteAttachmentResolverRequest
from .velt_sdk import get_velt_sdk

@csrf_exempt
@require_http_methods(["POST"])
def delete_attachment(request):
    try:
        data = json.loads(request.body)
        delete_request = DeleteAttachmentResolverRequest.from_dict(data)
        sdk = get_velt_sdk()
        result = sdk.selfHosting.attachments.deleteAttachment(delete_request)
        return JsonResponse(result, status=result.get('statusCode', 200))
    except Exception as e:
        return JsonResponse({
            'success': False,
            'error': str(e),
            'errorCode': 'INTERNAL_ERROR',
            'statusCode': 500
        }, status=500)

from flask import request, jsonify
from velt_py import DeleteAttachmentResolverRequest

@app.route('/api/velt/attachments/delete', methods=['POST'])
def delete_attachment():
    try:
        data = request.json
        delete_request = DeleteAttachmentResolverRequest.from_dict(data)
        result = sdk.selfHosting.attachments.deleteAttachment(delete_request)
        return jsonify(result), result.get('statusCode', 200)
    except Exception as e:
        return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500

from fastapi import Request
from fastapi.responses import JSONResponse
from velt_py import DeleteAttachmentResolverRequest

@app.post('/api/velt/attachments/delete')
async def delete_attachment(request: Request):
    try:
        data = await request.json()
        delete_request = DeleteAttachmentResolverRequest.from_dict(data)
        result = sdk.selfHosting.attachments.deleteAttachment(delete_request)
        return JSONResponse(content=result, status_code=result.get('statusCode', 200))
    except Exception as e:
        return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)

Response

{ 'success': True, 'statusCode': 200, 'data': { ... } }

Token

`getToken`

Generates a Velt auth token for a user. Self-hosting variant.
Params: positional — organizationId, userId, email (optional), isAdmin (optional)
Returns: VeltSelfHostingResponse

result = sdk.selfHosting.token.getToken(
    organizationId='org-123',
    userId='user-1',
    email='user@example.com',
    isAdmin=False
)

Response

{
    'success': True,
    'statusCode': 200,
    'data': { 'token': 'eyJhbGciOi...' }
}

Note: getToken takes positional / keyword arguments — it does NOT accept a dataclass request object. Signature: getToken(organizationId, userId, email=None, isAdmin=False).

Framework Examples

Django
Flask
FastAPI

SDK Initialization (velt_sdk.py)

from django.conf import settings
from velt_py import VeltSDK

_velt_sdk = None

def get_velt_sdk():
    global _velt_sdk
    if _velt_sdk is None:
        _velt_sdk = VeltSDK.initialize(settings.VELT_SDK_CONFIG)
    return _velt_sdk

API Endpoints (views.py)

import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from velt_py import GetCommentResolverRequest, SaveCommentResolverRequest, DeleteCommentResolverRequest
from .velt_sdk import get_velt_sdk

@csrf_exempt
@require_http_methods(["POST"])
def get_comments(request):
    try:
        data = json.loads(request.body)
        comment_request = GetCommentResolverRequest.from_dict(data)
        sdk = get_velt_sdk()
        result = sdk.selfHosting.comments.getComments(comment_request)
        return JsonResponse(result, status=result.get('statusCode', 200))
    except Exception as e:
        return JsonResponse({
            'success': False,
            'error': str(e),
            'errorCode': 'INTERNAL_ERROR',
            'statusCode': 500
        }, status=500)

Configuration (settings.py)

import os

VELT_SDK_CONFIG = {
    'database': {
        'connection_string': os.environ.get('VELT_MONGODB_CONNECTION_STRING'),
    },
    'aws': {
        'bucket_name': os.environ.get('AWS_S3_BUCKET'),
        'region': os.environ.get('AWS_REGION', 'us-east-1'),
        'access_key_id': os.environ.get('AWS_ACCESS_KEY_ID'),
        'secret_access_key': os.environ.get('AWS_SECRET_ACCESS_KEY'),
    },
    'apiKey': os.environ.get('VELT_API_KEY'),
    'authToken': os.environ.get('VELT_AUTH_TOKEN')
}

from flask import Flask, request, jsonify
from velt_py import VeltSDK, GetCommentResolverRequest, SaveCommentResolverRequest, DeleteCommentResolverRequest

app = Flask(__name__)

sdk = VeltSDK.initialize({
    'database': { 'connection_string': 'mongodb+srv://...' }
})

@app.route('/api/velt/comments/get', methods=['POST'])
def get_comments():
    data = request.json
    comment_request = GetCommentResolverRequest.from_dict(data)
    result = sdk.selfHosting.comments.getComments(comment_request)
    return jsonify(result), result.get('statusCode', 200)

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from velt_py import VeltSDK, GetCommentResolverRequest

app = FastAPI()

sdk = VeltSDK.initialize({
    'database': { 'connection_string': 'mongodb+srv://...' }
})

@app.post('/api/velt/comments/get')
async def get_comments(request: Request):
    data = await request.json()
    comment_request = GetCommentResolverRequest.from_dict(data)
    result = sdk.selfHosting.comments.getComments(comment_request)
    return JSONResponse(content=result, status_code=result.get('statusCode', 200))

REST API Backend

Added in v0.1.9. The sdk.api.* namespace provides feature parity with the Velt Node SDK for REST. 17 services are available, each accepting typed @dataclass request objects and returning the raw Velt API response without local reshaping. No database or AWS configuration is required — only apiKey and authToken.

from velt_py import VeltSDK

sdk = VeltSDK.initialize({
    'apiKey': 'YOUR_VELT_API_KEY',
    'authToken': 'YOUR_VELT_AUTH_TOKEN'
})

# All 17 services are accessible under sdk.api.*
# e.g. sdk.api.organizations, sdk.api.documents, sdk.api.workspace ...

Every method returns a dict with either a result key (success) or an error key (failure). See VeltApiResponse.

Organizations

`addOrganizations`

Creates one or more organizations.
Params: AddOrganizationsRequest
Returns: VeltApiResponse

from velt_py.models.organization import AddOrganizationsRequest

result = sdk.api.organizations.addOrganizations(
    AddOrganizationsRequest(
        organizations=[{'organizationId': 'yourOrganizationId', 'organizationName': 'Your Organization Name'}]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Organization(s) added successfully.',
        'data': {
            'yourOrganizationId': {
                'success': True,
                'id': '02cf91e5e7a5f4c0b600c84cf248384b',
                'message': 'Added Successfully'
            }
        }
    }
}

`getOrganizations`

Retrieves organizations by ID, with optional pagination.
Params: GetOrganizationsRequest
Returns: GetOrganizationsResponse

from velt_py.models.organization import GetOrganizationsRequest

result = sdk.api.organizations.getOrganizations(
    GetOrganizationsRequest(
        organizationIds=['yourOrganizationId'],
        pageSize=1000,
        pageToken='pageToken'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Organization(s) retrieved successfully.',
        'data': [
            {
                'id': 'yourOrganizationId',
                'organizationName': 'Your Organization Name',
                'disabled': False
                # other metadata fields may be included here
            }
            # ... more organizations if multiple were retrieved
        ],
        'nextPageToken': 'pageToken'
    }
}

`updateOrganizations`

Updates properties of one or more organizations.
Params: UpdateOrganizationsRequest
Returns: VeltApiResponse

from velt_py.models.organization import UpdateOrganizationsRequest

result = sdk.api.organizations.updateOrganizations(
    UpdateOrganizationsRequest(
        organizations=[{'organizationId': 'yourOrganizationId', 'organizationName': 'Updated Name'}]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Organization(s) updated successfully.',
        'data': {
            'yourOrganizationId': {
                'success': True,
                'id': '02cf91e5e7a5f4c0b600c84cf248384b',
                'message': 'Updated Successfully'
            }
        }
    }
}

`deleteOrganizations`

Deletes one or more organizations.
Params: DeleteOrganizationsRequest
Returns: VeltApiResponse

from velt_py.models.organization import DeleteOrganizationsRequest

result = sdk.api.organizations.deleteOrganizations(
    DeleteOrganizationsRequest(organizationIds=['yourOrganizationId1', 'yourOrganizationId2'])
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Organization(s) deleted successfully.',
        'data': {
            'yourOrganizationId1': {
                'success': True,
                'id': '02cf91e5e7a5f4c0b600c84cf248384b',
                'message': 'Deleted Successfully'
            },
            'yourOrganizationId2': {
                'success': False,
                'id': '02cf91e5e7a5f4c0b600c84cf248384b',
                'message': 'Organization does not exist'
            }
        }
    }
}

`updateOrganizationDisableState`

Enables or disables access to one or more organizations.
Params: UpdateOrganizationDisableStateRequest
Returns: VeltApiResponse

from velt_py.models.organization import UpdateOrganizationDisableStateRequest

result = sdk.api.organizations.updateOrganizationDisableState(
    UpdateOrganizationDisableStateRequest(
        organizationIds=['yourOrganizationId1', 'yourOrganizationId2'],
        disabled=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Updated disable state for Organization(s) successfully.',
        'data': {
            'yourOrganizationId1': {
                'success': True,
                'id': '02cf91e5e7a5f4c0b600c84cf248384b',
                'message': 'Updated disable state for organization Successfully'
            },
            'yourOrganizationId2': {
                'success': False,
                'id': '44e0132f4c6b0d453f18df42d2263b4e',
                'message': 'Organization does not exist'
            }
        }
    }
}

Folders

`addFolder`

Creates one or more folders inside an organization.
Params: AddFolderRequest
Returns: VeltApiResponse

from velt_py.models.folder import AddFolderRequest

result = sdk.api.folders.addFolder(
    AddFolderRequest(
        organizationId='yourOrganizationId',
        folders=[{
            'folderId': 'yourFolderId',
            'folderName': 'yourFolderName',
            'parentFolderId': 'yourParentFolderId'
        }]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Folder created successfully.',
        'data': {
            'yourFolderId': {
                'success': True,
                'id': 'yourFolderId',
                'message': 'Folder added.'
            }
        }
    }
}

`getFolders`

Retrieves folders within an organization.
Params: GetFoldersRequest
Returns: GetFoldersResponse

from velt_py.models.folder import GetFoldersRequest

result = sdk.api.folders.getFolders(
    GetFoldersRequest(organizationId='yourOrganizationId', folderId='yourFolderId')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Folders retrieved successfully.',
        'data': [
            {
                'folderId': 'folderId1',
                'folderName': 'Folder 1',
                'organizationId': 'yourOrganizationId',
                'parentFolderId': 'root',
                'createdAt': 1738695077691,
                'lastUpdated': 1738695077691,
                'subFolders': [
                    {
                        'folderId': 'childFolderId1',
                        'folderName': 'Child Folder 1',
                        'parentFolderId': 'folderId1',
                        'createdAt': 1738695615706,
                        'lastUpdated': 1738698727591
                    }
                ]
            }
        ]
    }
}

`updateFolder`

Updates properties of one or more folders.
Params: UpdateFolderRequest
Returns: VeltApiResponse

from velt_py.models.folder import UpdateFolderRequest

result = sdk.api.folders.updateFolder(
    UpdateFolderRequest(
        organizationId='yourOrganizationId',
        folders=[{'folderId': 'yourFolderId', 'folderName': 'yourFolderName', 'parentFolderId': 'yourParentFolderId'}]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Folder Updated successfully.',
        'data': {
            'yourFolderId': {
                'success': True,
                'id': 'yourFolderId',
                'message': 'Folder Updated.'
            }
        }
    }
}

`deleteFolder`

Deletes a folder.
Params: DeleteFolderRequest
Returns: VeltApiResponse

from velt_py.models.folder import DeleteFolderRequest

result = sdk.api.folders.deleteFolder(
    DeleteFolderRequest(organizationId='yourOrganizationId', folderId='yourFolderId')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Folder deleted successfully.',
        'data': { 'yourFolderId': {'success': True} }
    }
}

`updateFolderAccess`

Updates the access type of one or more folders.
Params: UpdateFolderAccessRequest
Returns: VeltApiResponse

from velt_py.models.folder import UpdateFolderAccessRequest

result = sdk.api.folders.updateFolderAccess(
    UpdateFolderAccessRequest(
        organizationId='yourOrganizationId',
        folderIds=['yourFolderId'],
        accessType='organizationPrivate'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Updated access for folders successfully.',
        'data': {
            'yourFolderId': {
                'success': True,
                'accessType': 'organizationPrivate',
                'message': 'Folder access type updated.'
            }
        }
    }
}

Documents

`addDocuments`

Creates one or more documents inside an organization.
Params: AddDocumentsRequest
Returns: VeltApiResponse

from velt_py.models.document import AddDocumentsRequest

result = sdk.api.documents.addDocuments(
    AddDocumentsRequest(
        organizationId='yourOrganizationId',
        documents=[{'documentId': 'yourDocumentId', 'documentName': 'yourDocumentName'}],
        createOrganization=True,
        folderId='yourFolderId',
        createFolder=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Document(s) added successfully.',
        'data': {
            'yourDocumentId': {
                'success': True,
                'id': '8121657101517513',
                'message': 'Added Successfully'
            }
        }
    }
}

`getDocuments`

Retrieves documents within an organization.
Params: GetDocumentsRequest
Returns: GetDocumentsResponse

from velt_py.models.document import GetDocumentsRequest

result = sdk.api.documents.getDocuments(
    GetDocumentsRequest(
        organizationId='yourOrganizationId',
        documentIds=['yourDocumentId'],
        folderId='yourFolderId'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Document(s) retrieved successfully.',
        'data': [
            {
                'documentName': 'yourDocumentName',
                'disabled': False,
                'accessType': 'public',
                'id': 'yourDocumentId'
            }
        ],
        'pageToken': 'nextPageToken'
    }
}

`updateDocuments`

Updates properties of one or more documents.
Params: UpdateDocumentsRequest
Returns: VeltApiResponse

from velt_py.models.document import UpdateDocumentsRequest

result = sdk.api.documents.updateDocuments(
    UpdateDocumentsRequest(
        organizationId='yourOrganizationId',
        documents=[{'documentId': 'yourDocumentId', 'documentName': 'Updated Name'}]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Document(s) updated successfully.',
        'data': {
            'yourDocumentId': {
                'success': True,
                'id': '8121657101517513',
                'message': 'Updated Successfully'
            }
        }
    }
}

`deleteDocuments`

Deletes one or more documents.
Params: DeleteDocumentsRequest
Returns: VeltApiResponse

from velt_py.models.document import DeleteDocumentsRequest

result = sdk.api.documents.deleteDocuments(
    DeleteDocumentsRequest(
        organizationId='yourOrganizationId',
        documentIds=['yourDocumentId1', 'yourDocumentId2']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Document(s) deleted successfully.',
        'data': {
            'yourDocumentId1': {
                'success': True,
                'id': '6737987049068973',
                'message': 'Deleted Successfully'
            },
            'yourDocumentId2': {
                'success': True,
                'id': '2131443384150904',
                'message': 'Document does not exist'
            }
        }
    }
}

`moveDocuments`

Moves documents into a target folder.
Params: MoveDocumentsRequest
Returns: VeltApiResponse

from velt_py.models.document import MoveDocumentsRequest

result = sdk.api.documents.moveDocuments(
    MoveDocumentsRequest(
        organizationId='yourOrganizationId',
        documentIds=['yourDocumentId1', 'yourDocumentId2'],
        folderId='target-folder-id'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Documents moved successfully.'
    }
}

`updateDocumentAccess`

Updates the access type of one or more documents.
Params: UpdateDocumentAccessRequest
Returns: VeltApiResponse

from velt_py.models.document import UpdateDocumentAccessRequest

result = sdk.api.documents.updateDocumentAccess(
    UpdateDocumentAccessRequest(
        organizationId='yourOrganizationId',
        documentIds=['yourDocumentId'],
        accessType='organizationPrivate'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Updated access for documents successfully.',
        'data': {
            'yourDocumentId': {
                'success': True,
                'accessType': 'organizationPrivate',
                'message': 'Document access type updated.'
            }
        }
    }
}

`updateDocumentDisableState`

Enables or disables access to one or more documents.
Params: UpdateDocumentDisableStateRequest
Returns: VeltApiResponse

from velt_py.models.document import UpdateDocumentDisableStateRequest

result = sdk.api.documents.updateDocumentDisableState(
    UpdateDocumentDisableStateRequest(
        organizationId='yourOrganizationId',
        documentIds=['yourDocumentId'],
        disabled=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Updated disable state for documents successfully.',
        'data': {
            'yourDocumentId': {
                'success': True,
                'disabled': True,
                'message': 'Document disabled state updated.'
            }
        }
    }
}

`migrateDocuments`

Starts a job to migrate a document to a new document ID.
Params: MigrateDocumentsRequest
Returns: MigrateDocumentsResponse

from velt_py.models.document import MigrateDocumentsRequest

result = sdk.api.documents.migrateDocuments(
    MigrateDocumentsRequest(
        organizationId='yourOrganizationId',
        documentId='old-doc-id',
        newDocumentId='new-doc-id'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Document migration started successfully.',
        'data': { 'migrationId': 'yourMigrationId' }
    }
}

Note: This call is asynchronous. Poll status via migrateDocumentsStatus.

`migrateDocumentsStatus`

Polls the status of a document migration job.
Params: MigrateDocumentsStatusRequest
Returns: MigrateDocumentsStatusResponse

from velt_py.models.document import MigrateDocumentsStatusRequest

result = sdk.api.documents.migrateDocumentsStatus(
    MigrateDocumentsStatusRequest(
        organizationId='yourOrganizationId',
        migrationId='yourMigrationId'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Migration status retrieved successfully.',
        'data': {
            'migrationId': 'yourMigrationId',
            'status': 'completed'
        }
    }
}

Users

`addUsers`

Adds one or more users to an organization.
Params: AddUsersRequest
Returns: VeltApiResponse

from velt_py.models.user_api import AddUsersRequest

result = sdk.api.users.addUsers(
    AddUsersRequest(
        organizationId='yourOrganizationId',
        users=[{'userId': 'yourUserId1', 'name': 'John Doe', 'email': 'john@example.com', 'accessRole': 'editor'}],
        createOrganization=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User(s) processed successfully.',
        'data': {
            'yourUserId1': {
                'success': True,
                'id': '4c250058149d6c9fb8c894c9ef29c790',
                'message': 'User added.'
            }
        }
    }
}

`getUsers`

Retrieves users in an organization or document.
Params: GetUsersRequest
Returns: GetUsersResponse

from velt_py.models.user_api import GetUsersRequest

result = sdk.api.users.getUsers(
    GetUsersRequest(
        organizationId='yourOrganizationId',
        userIds=['yourUserId'],
        documentId='yourDocumentId',
        pageSize=100,
        allDocuments=True,
        groupByDocumentId=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User(s) retrieved successfully.',
        'data': [
            {'email': 'userEmail@domain.com', 'name': 'userName', 'userId': 'yourUserId'}
        ],
        'nextPageToken': 'pageToken'
    }
}

`updateUsers`

Updates metadata for one or more users.
Params: UpdateUsersRequest
Returns: VeltApiResponse

from velt_py.models.user_api import UpdateUsersRequest

result = sdk.api.users.updateUsers(
    UpdateUsersRequest(
        organizationId='yourOrganizationId',
        users=[{'userId': 'yourUserId1', 'name': 'Jane Doe', 'accessRole': 'viewer'}]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User(s) processed successfully.',
        'data': {
            'yourUserId1': {
                'success': True,
                'id': '7d87015b055a168b098cf05b870e40ff',
                'message': 'User updated.'
            }
        }
    }
}

`deleteUsers`

Removes users from an organization.
Params: DeleteUsersRequest
Returns: VeltApiResponse

from velt_py.models.user_api import DeleteUsersRequest

result = sdk.api.users.deleteUsers(
    DeleteUsersRequest(
        organizationId='yourOrganizationId',
        userIds=['yourUserId1', 'yourUserId2']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User(s) deleted successfully.',
        'data': {
            'yourUserId1': {
                'success': True,
                'message': 'User removed.'
            }
        }
    }
}

User Groups

`addUserGroups`

Creates one or more user groups inside an organization.
Params: AddUserGroupsRequest
Returns: VeltApiResponse

from velt_py.models.user_group import AddUserGroupsRequest

result = sdk.api.userGroups.addUserGroups(
    AddUserGroupsRequest(
        organizationId='yourOrganizationId',
        organizationUserGroups=[{'groupId': 'yourGroupId', 'groupName': 'Engineering'}],
        createOrganization=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Organization User Groups added successfully.',
        'data': {
            'yourGroupId': {
                'success': True,
                'id': '77ab6767b022ad0323ba39c24f12cc95',
                'message': 'Organization user group added.'
            }
        }
    }
}

`addUsersToGroup`

Adds users to an existing group.
Params: AddUsersToGroupRequest
Returns: VeltApiResponse

from velt_py.models.user_group import AddUsersToGroupRequest

result = sdk.api.userGroups.addUsersToGroup(
    AddUsersToGroupRequest(
        organizationId='yourOrganizationId',
        organizationUserGroupId='yourGroupId',
        userIds=['yourUserId1', 'yourUserId2']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Added organization users to group successfully.',
        'data': {
            'yourUserId1': {
                'success': True,
                'organizationUserGroupId': 'yourGroupId',
                'message': 'User added to organization user group.'
            }
        }
    }
}

`deleteUsersFromGroup`

Removes users from a group, or empties the group entirely when deleteAll is True.
Params: DeleteUsersFromGroupRequest
Returns: VeltApiResponse

from velt_py.models.user_group import DeleteUsersFromGroupRequest

result = sdk.api.userGroups.deleteUsersFromGroup(
    DeleteUsersFromGroupRequest(
        organizationId='yourOrganizationId',
        organizationUserGroupId='yourGroupId',
        userIds=['yourUserId1'],
        deleteAll=False
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Deleted users from group successfully.',
        'data': {
            'yourUserId1': {
                'success': True,
                'organizationUserGroupId': 'yourGroupId',
                'message': 'User deleted from organization user group.'
            }
        }
    }
}

Notifications

`addNotifications`

Sends a notification to one or more users on a document.
Params: AddNotificationsRequest
Returns: VeltApiResponse

from velt_py.models.notification_api import AddNotificationsRequest

result = sdk.api.notifications.addNotifications(
    AddNotificationsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        actionUser={'userId': 'user-1', 'name': 'John Doe', 'email': 'john@example.com'},
        displayHeadlineMessageTemplate='{actionUser} commented on your document',
        displayBodyMessage='Check out the new comment',
        notifyUsers=[{'userId': 'user-2', 'name': 'Jane Doe'}],
        createOrganization=True,
        createDocument=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Notification added successfully.',
        'data': {
            'success': True,
            'message': 'Notification added successfully.'
        }
    }
}

`getNotifications`

Retrieves notifications for a user or document.
Params: GetNotificationsRequest
Returns: GetNotificationsResponse

from velt_py.models.notification_api import GetNotificationsRequest

result = sdk.api.notifications.getNotifications(
    GetNotificationsRequest(
        organizationId='yourOrganizationId',
        userId='user-2',
        pageSize=10,
        order='desc'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Notification(s) retrieved successfully.',
        'data': [
            {
                'id': 'notificationId',
                'notificationSource': 'custom',
                'notificationSourceData': {},
                'actionUser': {'email': 'user@example.com', 'name': 'User Name', 'userId': 'yourUserId'},
                'displayBodyMessage': 'This is body message (Secondary message)',
                'displayHeadlineMessageTemplate': 'Template with {actionUser}, {recipientUser}, {customVar}',
                'displayHeadlineMessageTemplateData': {
                    'actionUser': {'email': 'user@example.com', 'name': 'User Name', 'userId': 'yourUserId'},
                    'recipientUser': {'email': 'recipient@example.com', 'name': 'Recipient Name', 'userId': 'recipientUserId'}
                },
                'metadata': {'apiKey': '...', 'documentId': '...', 'organizationId': '...'},
                'notifyUsers': {'yourNotifyUserId': True},
                'notifyUsersByUserId': {'yourNotifyUserById': True},
                'timestamp': 1722409519944
            }
        ],
        'pageToken': 'nextPageToken'
    }
}

`updateNotifications`

Updates fields on existing notifications (e.g., mark as read).
Params: UpdateNotificationsRequest
Returns: VeltApiResponse

from velt_py.models.notification_api import UpdateNotificationsRequest

result = sdk.api.notifications.updateNotifications(
    UpdateNotificationsRequest(
        organizationId='yourOrganizationId',
        notifications={'5471488637912692': {'isRead': True}}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Notification(s) updated successfully.',
        'data': {
            '5471488637912692': {
                'success': True,
                'message': 'Notification updated.'
            }
        }
    }
}

`deleteNotifications`

Deletes one or more notifications.
Params: DeleteNotificationsRequest
Returns: VeltApiResponse

from velt_py.models.notification_api import DeleteNotificationsRequest

result = sdk.api.notifications.deleteNotifications(
    DeleteNotificationsRequest(
        organizationId='yourOrganizationId',
        notificationIds=['8955243231506071']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Notification(s) deleted successfully.',
        'data': {
            '8955243231506071': {
                'success': True,
                'message': 'Notification deleted.'
            }
        }
    }
}

`getNotificationConfig`

Gets notification preferences (inbox/email/slack channels) for a user.
Params: GetNotificationConfigRequest
Returns: GetNotificationConfigResponse

from velt_py.models.notification_api import GetNotificationConfigRequest

result = sdk.api.notifications.getNotificationConfig(
    GetNotificationConfigRequest(
        organizationId='org1',
        userId='USER_ID1'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User config fetched successfully.',
        'data': [
            {
                'config': {'inbox': 'ALL', 'email': 'ALL'},
                'metadata': {
                    'organizationId': 'org1',
                    'apiKey': 'API_KEY',
                    'documentId': 'doc1',
                    'userId': 'USER_ID1'
                }
            }
        ]
    }
}

`setNotificationConfig`

Sets notification preferences for one or more users.
Params: SetNotificationConfigRequest
Returns: VeltApiResponse

from velt_py.models.notification_api import SetNotificationConfigRequest

result = sdk.api.notifications.setNotificationConfig(
    SetNotificationConfigRequest(
        organizationId='org1',
        userIds=['USER_ID1'],
        config={'inbox': 'ALL', 'email': 'MINE'}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User config set successfully.',
        'data': {
            'USER_ID1': {
                'success': True,
                'userId': 'USER_ID1',
                'documentId': 'doc1',
                'message': 'User config set successfully.'
            }
        }
    }
}

Comment Annotations

`addCommentAnnotations`

Creates one or more comment annotations on a document.
Params: AddCommentAnnotationsRequest
Returns: VeltApiResponse

from velt_py.models.comment_annotation_api import AddCommentAnnotationsRequest

result = sdk.api.commentAnnotations.addCommentAnnotations(
    AddCommentAnnotationsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        commentAnnotations=[{
            'location': {'id': 'yourLocationId', 'locationName': 'yourLocationName'},
            'commentData': [{
                'commentText': 'Sample Comment',
                'commentHtml': '<div>Sample Comment</div>',
                'from': {'userId': 'yourUserId', 'name': 'yourUserName', 'email': 'yourUserEmail'}
            }]
        }]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Comment Annotation(s) added successfully.',
        'data': {
            '-O0mpUziLcBwzREvZKs6': {
                'success': True,
                'annotationId': '-O0mpUziLcBwzREvZKs6',
                'commentIds': [126535],
                'message': 'Added Successfully'
            }
        }
    }
}

`getCommentAnnotations`

Retrieves comment annotations on a document.
Params: GetCommentAnnotationsRequest
Returns: GetCommentAnnotationsResponse

from velt_py.models.comment_annotation_api import GetCommentAnnotationsRequest

result = sdk.api.commentAnnotations.getCommentAnnotations(
    GetCommentAnnotationsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        statusIds=['OPEN'],
        pageSize=10
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Annotation(s) fetched successfully.',
        'data': [
            {
                'annotationId': 'yourAnnotationId',
                'annotationNumber': 2,
                'type': 'comment',
                'createdAt': 1777973713421,
                'lastUpdated': 1777978714209,
                'hasDraftComments': False,
                'context': {'access': {'default': 'velt'}, 'accessFields': ['default:velt']},
                'visibilityConfig': {'type': 'public'},
                'metadata': {'apiKey': '...', 'organizationId': '...', 'documentId': '...'},
                'from': {'userId': 'user123', 'name': 'John Doe', 'email': 'john.doe@example.com'},
                'comments': [
                    {
                        'commentId': 123456,
                        'commentText': 'This is a sample comment text.',
                        'commentHtml': '<p>This is a sample comment text.</p>',
                        'createdAt': 1777973714914,
                        'lastUpdated': '2026-05-05T09:35:15.048Z',
                        'reactionAnnotationIds': ['reactionAnnotationId1'],
                        'from': {'userId': 'user123', 'name': 'John Doe'}
                    }
                ],
                'status': {'id': 'OPEN', 'name': 'Open', 'type': 'default'}
            }
        ],
        'nextPageToken': 'pageToken'
    }
}

`getCommentAnnotationsCount`

Counts total and unread annotations across one or more documents.
Params: GetCommentAnnotationsCountRequest
Returns: GetCommentAnnotationsCountResponse

from velt_py.models.comment_annotation_api import GetCommentAnnotationsCountRequest

result = sdk.api.commentAnnotations.getCommentAnnotationsCount(
    GetCommentAnnotationsCountRequest(
        organizationId='ORG_ID',
        documentIds=['DOC_1', 'DOC_2'],
        userId='1.1',
        statusIds=['OPEN', 'IN_PROGRESS']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Comment count retrieved successfully.',
        'data': {
            'DOC_1': {'total': 4, 'unread': 2},
            'DOC_2': {'total': 2, 'unread': 0}
        }
    }
}

`updateCommentAnnotations`

Updates annotation fields (e.g., change status).
Params: UpdateCommentAnnotationsRequest
Returns: VeltApiResponse

from velt_py.models.comment_annotation_api import UpdateCommentAnnotationsRequest

result = sdk.api.commentAnnotations.updateCommentAnnotations(
    UpdateCommentAnnotationsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        annotationIds=['yourAnnotationId1'],
        updatedData={'status': {'id': 'inprogress', 'name': 'In Progress', 'type': 'ongoing'}}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Annotations updated successfully.',
        'data': {
            'yourAnnotationId1': {
                'success': True,
                'id': 'yourAnnotationId1',
                'message': 'Annotations updated successfully'
            }
        }
    }
}

`deleteCommentAnnotations`

Deletes one or more comment annotations.
Params: DeleteCommentAnnotationsRequest
Returns: VeltApiResponse

from velt_py.models.comment_annotation_api import DeleteCommentAnnotationsRequest

result = sdk.api.commentAnnotations.deleteCommentAnnotations(
    DeleteCommentAnnotationsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        annotationIds=['yourAnnotationId1', 'yourAnnotationId2']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Annotations deleted successfully.',
        'data': {
            'yourAnnotationId1': {
                'success': True,
                'id': 'yourAnnotationId',
                'message': 'Deleted Successfully'
            },
            'yourAnnotationId2': {
                'success': False,
                'id': 'yourAnnotationId2',
                'message': 'Annotation not found.'
            }
        }
    }
}

`addComments`

Adds reply comments to an existing annotation.
Params: AddCommentsRequest
Returns: VeltApiResponse

from velt_py.models.comment_annotation_api import AddCommentsRequest

result = sdk.api.commentAnnotations.addComments(
    AddCommentsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        annotationId='yourAnnotationId',
        commentData=[{
            'commentText': 'I agree, let me fix this',
            'from': {'userId': 'user-2', 'name': 'Jane Doe'}
        }]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Comment(s) added successfully.',
        'data': [778115]
    }
}

`getComments`

Retrieves individual comments inside an annotation.
Params: GetCommentsRequest
Returns: GetCommentsResponse

from velt_py.models.comment_annotation_api import GetCommentsRequest

result = sdk.api.commentAnnotations.getComments(
    GetCommentsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        annotationId='yourAnnotationId',
        userIds=['yourUserId']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Comments retrieved successfully.',
        'data': [
            {
                'commentId': 123456,
                'type': 'text',
                'commentText': 'This is a sample comment text.',
                'commentHtml': '<p>This is a sample comment text.</p>',
                'createdAt': 1777973714914,
                'lastUpdated': '2026-05-05T09:35:15.048Z',
                'reactionAnnotationIds': ['reactionAnnotationId1'],
                'from': {'userId': 'user123', 'name': 'John Doe', 'email': 'john.doe@example.com'}
            }
        ]
    }
}

`updateComments`

Updates fields on individual comments inside an annotation.
Params: UpdateCommentsRequest
Returns: VeltApiResponse

from velt_py.models.comment_annotation_api import UpdateCommentsRequest

result = sdk.api.commentAnnotations.updateComments(
    UpdateCommentsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        annotationId='yourAnnotationId',
        commentIds=[607395],
        updatedData={'commentText': 'Updated text', 'commentHtml': '<p>Updated text</p>'}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Comment updated successfully.',
        'data': {
            '607395': {
                'success': True,
                'id': 607395,
                'message': 'Updated successfully'
            }
        }
    }
}

`deleteComments`

Deletes one or more comments from an annotation, or all comments if commentIds is omitted.
Params: DeleteCommentsRequest
Returns: VeltApiResponse

from velt_py.models.comment_annotation_api import DeleteCommentsRequest

result = sdk.api.commentAnnotations.deleteComments(
    DeleteCommentsRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        annotationId='yourAnnotationId',
        commentIds=[153783, 607395]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Comments(s) deleted successfully.',
        'data': {
            '153783': {
                'success': True,
                'id': 153783,
                'message': 'Deleted successfully'
            },
            '607395': {
                'success': False,
                'id': 607395,
                'message': 'Not found'
            }
        }
    }
}

Activities

`addActivities`

Logs one or more activity events.
Params: AddActivitiesRequest
Returns: VeltApiResponse

from velt_py.models.activity_api import AddActivitiesRequest

result = sdk.api.activities.addActivities(
    AddActivitiesRequest(
        organizationId='org-123',
        documentId='doc-456',
        activities=[{
            'featureType': 'comment',
            'actionType': 'comment.add',
            'actionUser': {'userId': 'user-1', 'name': 'User Name', 'email': 'user@example.com'},
            'displayMessageTemplate': '{{user}} added a comment'
        }]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Activity(s) added successfully.',
        'data': {
            'success': True,
            'message': 'Activity(s) added successfully.'
        }
    }
}

`getActivities`

Retrieves activities with optional filters and pagination.
Params: GetActivitiesRequest
Returns: GetActivitiesResponse

from velt_py.models.activity_api import GetActivitiesRequest

result = sdk.api.activities.getActivities(
    GetActivitiesRequest(
        organizationId='org-123',
        documentId='doc-456',
        featureTypes=['comment'],
        order='desc',
        pageSize=50
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Activity(s) retrieved successfully.',
        'data': [
            {
                'id': 'activity-001',
                'featureType': 'comment',
                'actionType': 'comment.add',
                'actionUser': {'userId': 'user-1', 'email': 'user@example.com', 'name': 'User Name'},
                'targetEntityId': 'annotation-789',
                'displayMessageTemplate': '{{user}} added a comment',
                'displayMessageTemplateData': {'user': {'userId': 'user-1', 'name': 'User Name'}},
                'metadata': {'apiKey': 'yourApiKey', 'documentId': 'doc-456', 'organizationId': 'org-123'},
                'timestamp': 1722409519944
            }
        ],
        'pageToken': 'nextPageToken'
    }
}

`updateActivities`

Updates fields on existing activities.
Params: UpdateActivitiesRequest
Returns: VeltApiResponse

from velt_py.models.activity_api import UpdateActivitiesRequest

result = sdk.api.activities.updateActivities(
    UpdateActivitiesRequest(
        organizationId='org-123',
        activities=[{
            'id': 'activity-001',
            'displayMessageTemplate': '{{user}} updated the comment'
        }]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Activity(s) updated successfully.',
        'data': {
            'activity-001': {
                'success': True,
                'message': 'Activity updated.'
            }
        }
    }
}

`deleteActivities`

Deletes activities by document, target entity, or specific IDs.
Params: DeleteActivitiesRequest
Returns: VeltApiResponse

from velt_py.models.activity_api import DeleteActivitiesRequest

result = sdk.api.activities.deleteActivities(
    DeleteActivitiesRequest(
        organizationId='org-123',
        activityIds=['activity-001', 'activity-002']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Activity(s) deleted successfully.',
        'data': {
            'activity-001': {
                'success': True,
                'message': 'Activity deleted.'
            }
        }
    }
}

Access Control

`addPermissions`

Grants resource-level permissions to a user.
Params: AddPermissionsRequest
Returns: VeltApiResponse

from velt_py.models.access_control import AddPermissionsRequest

result = sdk.api.accessControl.addPermissions(
    AddPermissionsRequest(
        user={'userId': 'some-user-id'},
        permissions={'resources': [
            {'type': 'organization', 'id': 'YOUR_ORGANIZATION_ID', 'accessRole': 'editor'},
            {'type': 'document', 'id': 'YOUR_DOCUMENT_ID', 'organizationId': 'YOUR_ORGANIZATION_ID', 'accessRole': 'viewer', 'expiresAt': 1728902400}
        ]}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Permissions added successfully.'
    }
}

`getPermissions`

Retrieves permissions for one or more users.
Params: GetPermissionsRequest
Returns: GetPermissionsResponse

from velt_py.models.access_control import GetPermissionsRequest

result = sdk.api.accessControl.getPermissions(
    GetPermissionsRequest(
        organizationId='org1',
        userIds=['1.1'],
        documentIds=['document1']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'User permissions retrieved successfully.',
        'data': {
            '1.1': {
                'folders': {
                    'folder2': {'accessRole': 'editor', 'accessType': 'restricted'}
                },
                'documents': {
                    'document1': {'accessRole': 'viewer', 'accessType': 'restricted'}
                },
                'organization': {
                    'org1': {'accessRole': 'editor'}
                }
            }
        }
    }
}

`removePermissions`

Revokes resource-level permissions from a user.
Params: RemovePermissionsRequest
Returns: VeltApiResponse

from velt_py.models.access_control import RemovePermissionsRequest

result = sdk.api.accessControl.removePermissions(
    RemovePermissionsRequest(
        userId='USER_ID',
        permissions={'resources': [
            {'type': 'organization', 'id': 'ORGANIZATION_ID'},
            {'type': 'document', 'id': 'DOCUMENT_ID', 'organizationId': 'ORGANIZATION_ID'}
        ]}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Permissions removed successfully.'
    }
}

`generateSignature`

Generates a signed payload for Velt’s Permission Provider flow.
Params: GenerateSignatureRequest
Returns: GenerateSignatureResponse

from velt_py.models.access_control import GenerateSignatureRequest

result = sdk.api.accessControl.generateSignature(
    GenerateSignatureRequest(
        permissions=[{
            'userId': 'user123',
            'resourceId': 'document456',
            'type': 'document',
            'hasAccess': True,
            'accessRole': 'viewer',
            'expiresAt': 1759745729823
        }]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Signature generated successfully.',
        'data': { 'signature': 'a1b2c3d4e5f6...' }
    }
}

`generateToken`

Generates a Velt JWT token bound to a user and a set of resource permissions.
Params: GenerateTokenRequest
Returns: GenerateTokenResponse

from velt_py.models.access_control import GenerateTokenRequest

result = sdk.api.accessControl.generateToken(
    GenerateTokenRequest(
        userId='user123',
        userProperties={'isAdmin': False, 'name': 'John Doe', 'email': 'john@example.com'},
        permissions={'resources': [
            {'type': 'organization', 'id': 'org_123', 'accessRole': 'viewer'},
            {'type': 'document', 'id': 'doc_456', 'organizationId': 'org_123', 'accessRole': 'editor', 'expiresAt': 1640995200}
        ]}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Token generated successfully.',
        'data': { 'token': 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' }
    }
}

CRDT

`addCrdtData`

Stores CRDT data (text, map, array, or xml) for an editor on a document.
Params: AddCrdtDataRequest
Returns: VeltApiResponse

from velt_py.models.crdt import AddCrdtDataRequest

result = sdk.api.crdt.addCrdtData(
    AddCrdtDataRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        editorId='my-collab-note',
        data='Hello, collaborative world!',
        type='text'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'CRDT data added successfully.'
    }
}

`getCrdtData`

Retrieves CRDT data for one or all editors on a document.
Params: GetCrdtDataRequest
Returns: GetCrdtDataResponse

from velt_py.models.crdt import GetCrdtDataRequest

result = sdk.api.crdt.getCrdtData(
    GetCrdtDataRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        editorId='my-collab-note'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'CRDT data retrieved successfully.',
        'data': [
            {
                'data': 'Hello, collaborative world!',
                'id': 'my-collab-note',
                'lastUpdate': '2025-01-20T10:30:00.000Z',
                'lastUpdatedBy': 'user-123',
                'sessionId': 'session-abc-456'
            }
        ]
    }
}

`updateCrdtData`

Updates existing CRDT data for an editor.
Params: UpdateCrdtDataRequest
Returns: VeltApiResponse

from velt_py.models.crdt import UpdateCrdtDataRequest

result = sdk.api.crdt.updateCrdtData(
    UpdateCrdtDataRequest(
        organizationId='yourOrganizationId',
        documentId='yourDocumentId',
        editorId='my-collab-note',
        data='Updated collaborative content!',
        type='text'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'CRDT data updated successfully.'
    }
}

Presence

`addPresence`

Adds users to a document’s presence list.
Params: AddPresenceRequest
Returns: VeltApiResponse

from velt_py.models.presence import AddPresenceRequest

result = sdk.api.presence.addPresence(
    AddPresenceRequest(
        organizationId='org-123',
        documentId='doc-456',
        users=[
            {'userId': 'user-1', 'name': 'John Doe', 'email': 'john@example.com', 'status': 'online'},
            {'userId': 'user-2', 'name': 'Jane Doe', 'status': 'away'}
        ]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Presence added successfully.',
        'data': { 'success': True }
    }
}

`updatePresence`

Updates presence status for one or more users on a document.
Params: UpdatePresenceRequest
Returns: VeltApiResponse

from velt_py.models.presence import UpdatePresenceRequest

result = sdk.api.presence.updatePresence(
    UpdatePresenceRequest(
        organizationId='org-123',
        documentId='doc-456',
        users=[{'userId': 'user-1', 'status': 'away'}]
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Presence updated successfully.',
        'data': { 'success': True }
    }
}

`deletePresence`

Removes users from a document’s presence list.
Params: DeletePresenceRequest
Returns: VeltApiResponse

from velt_py.models.presence import DeletePresenceRequest

result = sdk.api.presence.deletePresence(
    DeletePresenceRequest(
        organizationId='org-123',
        documentId='doc-456',
        userIds=['user-1', 'user-2']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Presence deleted successfully.',
        'data': { 'success': True }
    }
}

Livestate

`broadcastEvent`

Broadcasts an event payload to all clients subscribed to a livestate ID on a document.
Params: BroadcastEventRequest
Returns: VeltApiResponse

from velt_py.models.livestate import BroadcastEventRequest

result = sdk.api.livestate.broadcastEvent(
    BroadcastEventRequest(
        organizationId='org-123',
        documentId='doc-1',
        liveStateDataId='my-live-state',
        data={'status': 'active', 'message': 'Hello World'},
        merge=True
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Event broadcasted successfully.',
        'data': { 'success': True }
    }
}

Recordings

`getRecordings`

Retrieves recording metadata, optionally scoped to a document or set of recording IDs.
Params: GetRecordingsRequest
Returns: GetRecordingsResponse

from velt_py.models.recording import GetRecordingsRequest

result = sdk.api.recordings.getRecordings(
    GetRecordingsRequest(
        organizationId='org-123',
        documentId='doc-456',
        recordingIds=['rec-1'],
        pageSize=10,
        pageToken='encryptedPageToken'
    )
)

Response

{
    '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'
    }
}

Rewriter

`askAi`

Sends a model, prompt, and text to Velt’s AI rewriter and returns the transformed text.
Params: AskAiRequest
Returns: AskAiResponse

from velt_py.models.rewriter import AskAiRequest

result = sdk.api.rewriter.askAi(
    AskAiRequest(
        model='gpt-4o',
        prompt='Fix the grammar and spelling in the following text.',
        text='Their going to the store to by some apples.'
    )
)

Response

{
    'result': {
        'success': True,
        'text': "They're going to the store to buy some apples."
    }
}

Note: This call may take several seconds and has no client-side timeout. Wrap calls in your own timeout if needed.

`deleteAllUserData`

Requests deletion of all data associated with one or more users.
Params: DeleteAllUserDataRequest
Returns: VeltApiResponse

from velt_py.models.gdpr import DeleteAllUserDataRequest

result = sdk.api.gdpr.deleteAllUserData(
    DeleteAllUserDataRequest(
        userIds=['user-1', 'user-2'],
        organizationIds=['org-123']
    )
)

Response

{
    'status': 'success',
    'message': 'Data deletion process has been initiated.',
    'data': {
        'jobId': 'dsQuvPmIynANgPLLEhCm',
        'tasksCount': 5
    },
    'statusCode': 202
}

Note: This call is asynchronous and returns a jobId. Poll status via getDeleteUserDataStatus.

`getAllUserData`

Exports all data associated with a user, paginated.
Params: GetAllUserDataRequest
Returns: GetAllUserDataResponse

from velt_py.models.gdpr import GetAllUserDataRequest

result = sdk.api.gdpr.getAllUserData(
    GetAllUserDataRequest(
        organizationId='org-123',
        userId='user-1',
        pageToken='next-page-token'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Data fetched successfully.',
        'data': {
            'comments': [],       # Up to 100 items per page.
            'reactions': [],      # Up to 100 items per page.
            'recordings': [],     # Up to 100 items per page.
            'notifications': []   # Up to 100 items per page.
        },
        'nextPageToken': 'bhdwdqwjs298e39e479ddkeuw==329'
    }
}

`getDeleteUserDataStatus`

Polls the status of a deleteAllUserData job.
Params: GetDeleteUserDataStatusRequest
Returns: GetDeleteUserDataStatusResponse

from velt_py.models.gdpr import GetDeleteUserDataStatusRequest

result = sdk.api.gdpr.getDeleteUserDataStatus(
    GetDeleteUserDataStatusRequest(jobId='job-id-from-delete-call')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Data fetched successfully.',
        'data': {
            'isDeleteCompleted': True,
            'tasksLeft': 0,
            'lastTaskCompletedTime': 1748972106739
        }
    }
}

Workspace

`createWorkspace`

Creates a new workspace.
Params: CreateWorkspaceRequest
Returns: VeltApiResponse

from velt_py.models.workspace import CreateWorkspaceRequest

result = sdk.api.workspace.createWorkspace(
    CreateWorkspaceRequest(
        ownerEmail='owner@example.com',
        workspaceName='My Workspace',
        name='John Doe'
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Workspace created successfully.',
        'data': {
            'id': 'workspace_abc123',
            'name': 'My Workspace',
            'owner': {
                'email': 'owner@example.com',
                'id': 'owner_id_123',
                'name': 'John Doe',
                'avatar': ''
            },
            'authToken': 'eyJhbGciOiJSUzI1NiIs...',
            'apiKeyList': {
                'velt_api_key_1': {
                    'apiKeyName': 'John Doe Test API Key',
                    'id': 'velt_api_key_1',
                    'type': 'testing'
                }
            }
        }
    }
}

`getWorkspace`

Retrieves details about the current workspace.
Params: GetWorkspaceRequest
Returns: GetWorkspaceResponse

from velt_py.models.workspace import GetWorkspaceRequest

result = sdk.api.workspace.getWorkspace(GetWorkspaceRequest())

Response

{
    'result': {
        'status': 'success',
        'message': 'Workspace retrieved successfully.',
        'data': {
            'id': 'workspace_abc123',
            'name': 'My Workspace',
            'owner': {
                'email': 'owner@example.com',
                'id': 'owner_id_123',
                'name': 'John Doe',
                'avatar': ''
            },
            'authToken': 'eyJhbGciOiJSUzI1NiIs...',
            'apiKeyList': {
                'velt_api_key_1': {
                    'apiKeyName': 'John Doe Test API Key',
                    'id': 'velt_api_key_1',
                    'type': 'testing'
                }
            }
        }
    }
}

`createApiKey`

Creates a new API key in the workspace.
Params: CreateApiKeyRequest
Returns: VeltApiResponse

from velt_py.models.workspace import CreateApiKeyRequest

result = sdk.api.workspace.createApiKey(
    CreateApiKeyRequest(
        ownerEmail='owner@example.com',
        type='production',
        createAuthToken=True,
        apiKeyName='Production Key',
        allowedDomains=['example.com', '*.example.com']
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'API key created successfully.',
        'data': { 'apiKey': 'your_new_api_key' }
    }
}

`updateApiKey`

Updates an existing API key (e.g., rename it).
Params: UpdateApiKeyRequest
Returns: VeltApiResponse

from velt_py.models.workspace import UpdateApiKeyRequest

result = sdk.api.workspace.updateApiKey(
    UpdateApiKeyRequest(apiKey='velt_api_key_1', apiKeyName='Renamed Key')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'API key updated successfully.',
        'data': None
    }
}

`getApiKeys`

Lists all API keys in the workspace.
Params: GetApiKeysRequest
Returns: GetApiKeysResponse

from velt_py.models.workspace import GetApiKeysRequest

result = sdk.api.workspace.getApiKeys(
    GetApiKeysRequest(pageSize=50, pageToken='next-page-token')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'API keys retrieved successfully.',
        'data': [
            {'id': 'velt_api_key_1', 'apiKeyName': 'Production Key', 'type': 'production'},
            {'id': 'velt_api_key_2', 'apiKeyName': 'Testing Key', 'type': 'testing'}
        ],
        'nextPageToken': 'eyJsYXN0SWQiOiJ2ZWx0X2FwaV9rZXlfMiJ9'
    }
}

`getApiKeyMetadata`

Gets metadata for the API key the SDK is authenticated with.
Params: GetApiKeyMetadataRequest
Returns: GetApiKeyMetadataResponse

from velt_py.models.workspace import GetApiKeyMetadataRequest

result = sdk.api.workspace.getApiKeyMetadata(GetApiKeyMetadataRequest())

Response

{
    'result': {
        'status': 'success',
        'message': 'API key metadata retrieved successfully.',
        'data': {
            'defaultDocumentAccessType': 'public',
            'planInfo': {'type': 'sdk test'},
            'ownerEmail': 'owner@example.com'
        }
    }
}

`resetAuthToken`

Rotates the auth token associated with an API key.
Params: ResetAuthTokenRequest
Returns: VeltApiResponse

from velt_py.models.workspace import ResetAuthTokenRequest

result = sdk.api.workspace.resetAuthToken(
    ResetAuthTokenRequest(apiKey='velt_api_key_1')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Auth token reset successfully.',
        'data': {
            'apiKey': 'velt_api_key_1',
            'newAuthToken': {
                'token': 'eyJhbGciOiJSUzI1NiIs...',
                'name': 'Default Auth Token',
                'domains': []
            }
        }
    }
}

`getAuthTokens`

Lists auth tokens for an API key.
Params: GetAuthTokensRequest
Returns: GetAuthTokensResponse

from velt_py.models.workspace import GetAuthTokensRequest

result = sdk.api.workspace.getAuthTokens(
    GetAuthTokensRequest(apiKey='velt_api_key_1')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Auth tokens retrieved successfully.',
        'data': {
            'apiKey': 'velt_api_key_1',
            'authTokens': [
                {'token': 'eyJhbGciOiJSUzI1NiIs...', 'name': 'Default Auth Token', 'domains': []}
            ]
        }
    }
}

`addDomains`

Adds allowed domains to the workspace.
Params: AddDomainsRequest
Returns: VeltApiResponse

from velt_py.models.workspace import AddDomainsRequest

result = sdk.api.workspace.addDomains(
    AddDomainsRequest(domains=['google.com', '*.firebase.com'])
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Domain(s) added successfully to allowed domains.',
        'data': {
            'domainsAdded': ['google.com', '*.firebase.com']
        }
    }
}

`deleteDomains`

Removes allowed domains from the workspace.
Params: DeleteDomainsRequest
Returns: VeltApiResponse

from velt_py.models.workspace import DeleteDomainsRequest

result = sdk.api.workspace.deleteDomains(
    DeleteDomainsRequest(domains=['google.com', '*.firebase.com'])
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Domain(s) removed successfully from allowed domains.',
        'data': {
            'domainsRemoved': ['google.com', '*.firebase.com']
        }
    }
}

`getDomains`

Lists allowed domains for the workspace.
Params: GetDomainsRequest
Returns: GetDomainsResponse

from velt_py.models.workspace import GetDomainsRequest

result = sdk.api.workspace.getDomains(GetDomainsRequest())

Response

{
    'result': {
        'status': 'success',
        'message': 'Allowed domains retrieved successfully.',
        'data': {
            'allowedDomains': ['localhost', '127.0.0.1', 'example.com']
        }
    }
}

`getEmailStatus`

Checks email verification status for a workspace owner.
Params: GetEmailStatusRequest
Returns: GetEmailStatusResponse

from velt_py.models.workspace import GetEmailStatusRequest

result = sdk.api.workspace.getEmailStatus(
    GetEmailStatusRequest(ownerEmail='owner@example.com')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Email verified and workspace reactivated',
        'data': { 'verified': True }
    }
}

`sendLoginLink`

Sends a login link email to a user.
Params: SendLoginLinkRequest
Returns: VeltApiResponse

from velt_py.models.workspace import SendLoginLinkRequest

result = sdk.api.workspace.sendLoginLink(
    SendLoginLinkRequest(email='user@example.com', continueUrl='https://app.example.com/dashboard')
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Login link sent successfully.',
        'data': None
    }
}

`getEmailConfig`

Retrieves the workspace’s email service configuration.
Params: GetEmailConfigRequest
Returns: GetEmailConfigResponse

from velt_py.models.workspace import GetEmailConfigRequest

result = sdk.api.workspace.getEmailConfig(GetEmailConfigRequest())

Response

{
    'result': {
        'status': 'success',
        'message': 'Email configuration retrieved successfully.',
        'data': {
            'useEmailService': False,
            'emailServiceConfig': {
                'type': 'default',
                'apiKey': '',
                'fromEmail': '',
                'fromCompany': '',
                'commentTemplateId': '',
                'tagTemplateId': ''
            }
        }
    }
}

`updateEmailConfig`

Updates the workspace’s email service configuration.
Params: UpdateEmailConfigRequest
Returns: VeltApiResponse

from velt_py.models.workspace import UpdateEmailConfigRequest

result = sdk.api.workspace.updateEmailConfig(
    UpdateEmailConfigRequest(
        useEmailService=True,
        emailServiceConfig={'type': 'sendgrid', 'apiKey': 'sg-key', 'fromEmail': 'noreply@example.com'}
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Email configuration updated successfully.',
        'data': None
    }
}

`getWebhookConfig`

Retrieves the workspace’s webhook configuration.
Params: GetWebhookConfigRequest
Returns: GetWebhookConfigResponse

from velt_py.models.workspace import GetWebhookConfigRequest

result = sdk.api.workspace.getWebhookConfig(GetWebhookConfigRequest())

Response

{
    'result': {
        'status': 'success',
        'message': 'Webhook configuration retrieved successfully.',
        'data': {
            'useWebhookService': False,
            'webhookServiceConfig': {
                'authToken': '',
                'rawNotificationUrl': '',
                'processedNotificationUrl': ''
            }
        }
    }
}

`updateWebhookConfig`

Updates the workspace’s webhook configuration.
Params: UpdateWebhookConfigRequest
Returns: VeltApiResponse

from velt_py.models.workspace import UpdateWebhookConfigRequest

result = sdk.api.workspace.updateWebhookConfig(
    UpdateWebhookConfigRequest(
        useWebhookService=True,
        webhookServiceConfig={
            'authToken': 'webhook-secret',
            'rawNotificationUrl': 'https://example.com/webhook/raw',
            'processedNotificationUrl': 'https://example.com/webhook/processed'
        }
    )
)

Response

{
    'result': {
        'status': 'success',
        'message': 'Webhook configuration updated successfully.',
        'data': None
    }
}

Token

`getToken`

Generates a Velt auth token for a user.
Params: positional — organizationId, userId, email (optional), isAdmin (optional)
Returns: VeltApiResponse

result = sdk.api.token.getToken(
    organizationId='org-123',
    userId='user-1',
    email='user@example.com',
    isAdmin=False
)

Response

{
    'result': {
        'status': 'success',
        'data': { 'token': 'eyJhbGciOi...' }
    }
}

Note: getToken takes positional / keyword arguments — it does NOT accept a dataclass request object. Signature: getToken(organizationId, userId, email=None, isAdmin=False).

Data Isolation

Every sdk.api.* method requires an organizationId in its request payload. Velt’s API enforces data isolation server-side — requests without a valid organizationId will be rejected.

Error Handling

The SDK raises typed exceptions for different failure modes. All exceptions extend VeltSDKError.

Exception	When raised
`VeltSDKError`	Base class; catch for any SDK-level error
`VeltValidationError`	SDK-level validation (e.g., missing required config); `sdk.api.*` methods do not validate request payloads locally
`VeltTokenError`	Token generation or authentication failure
`VeltApiError`	REST API errors (network failures, unexpected responses)

from velt_py.exceptions import VeltSDKError, VeltApiError

try:
    result = sdk.api.organizations.addOrganizations(
        AddOrganizationsRequest(organizations=[{'organizationId': 'org-123'}])
    )
except VeltApiError as e:
    print(f'API error: {e.message}')
except VeltSDKError as e:
    print(f'SDK error: {e.message}')

Import path: from velt_py.exceptions import VeltSDKError, VeltValidationError, VeltTokenError, VeltApiError Common self-hosting error codes returned in the response errorCode field:

INVALID_INPUT — Request data is malformed or missing required fields
INTERNAL_ERROR — Server-side error during processing
NOT_FOUND — Requested resource was not found

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Documentation Index

​Overview

​Installation

​Requirements

​Quick Start

​Initialize the SDK

​Configuration

​Environment Variables

​Self-Hosting Configuration

​Self-Hosting Backend

​Comments

​getComments

​saveComments

​deleteComment

​Reactions

​getReactions

​saveReactions

​deleteReaction

​Users

​getUsers

​Attachments

​saveAttachment

​deleteAttachment

​Token

​getToken

​Framework Examples

​REST API Backend

​Organizations

​addOrganizations

​getOrganizations

​updateOrganizations

​deleteOrganizations

​updateOrganizationDisableState

​Folders

​addFolder

​getFolders

​updateFolder

​deleteFolder

​updateFolderAccess

​Documents

​addDocuments

​getDocuments

​updateDocuments

​deleteDocuments

​moveDocuments

​updateDocumentAccess

​updateDocumentDisableState

​migrateDocuments

​migrateDocumentsStatus

​Users

​addUsers

​getUsers

​updateUsers

​deleteUsers

​User Groups

​addUserGroups

​addUsersToGroup

​deleteUsersFromGroup

​Notifications

​addNotifications

​getNotifications

​updateNotifications

​deleteNotifications

​getNotificationConfig

​setNotificationConfig

​Comment Annotations

​addCommentAnnotations

​getCommentAnnotations

Overview

Installation

Requirements

Quick Start

Initialize the SDK

Configuration

Environment Variables

Self-Hosting Configuration

Self-Hosting Backend

Comments

`getComments`

`saveComments`

`deleteComment`

Reactions

`getReactions`

`saveReactions`

`deleteReaction`

Users

`getUsers`

Attachments

`saveAttachment`

`deleteAttachment`

Token

`getToken`

Framework Examples

REST API Backend

Organizations

`addOrganizations`

`getOrganizations`

`updateOrganizations`

`deleteOrganizations`

`updateOrganizationDisableState`

Folders

`addFolder`

`getFolders`

`updateFolder`

`deleteFolder`

`updateFolderAccess`

Documents

`addDocuments`

`getDocuments`

`updateDocuments`

`deleteDocuments`

`moveDocuments`

`updateDocumentAccess`

`updateDocumentDisableState`

`migrateDocuments`

`migrateDocumentsStatus`

Users

`addUsers`

`getUsers`

`updateUsers`

`deleteUsers`

User Groups

`addUserGroups`

`addUsersToGroup`

`deleteUsersFromGroup`

Notifications

`addNotifications`

`getNotifications`

`updateNotifications`

`deleteNotifications`

`getNotificationConfig`

`setNotificationConfig`

Comment Annotations

`addCommentAnnotations`

`getCommentAnnotations`

`getCommentAnnotationsCount`

`updateCommentAnnotations`

`deleteCommentAnnotations`

`addComments`

`getComments`

`updateComments`

`deleteComments`

Activities

`addActivities`

`getActivities`

`updateActivities`

`deleteActivities`

Access Control