> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Python
> Use the Velt Python SDK for self-hosting backend implementation or calling Velt's REST APIs directly. Covers both sdk.selfHosting.* (MongoDB + AWS S3) and sdk.api.* (REST API, no database needed).
## Overview
The [Velt Python SDK](https://pypi.org/project/velt-py) 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:
1. Pass your DB and storage configs to the SDK
2. Pass the raw request object directly to SDK methods
3. 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
```bash theme={null}
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):
```python theme={null}
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):
```python theme={null}
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
Configure MongoDB connection for storing comments, reactions, and user data.
```python theme={null}
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.
```python theme={null}
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.
```python theme={null}
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.
```python theme={null}
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.
```python theme={null}
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](/api-reference/sdk/models/data-models#getcommentresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{
'success': True,
'statusCode': 200,
'data': { 'comments': [ ... ] }
}
```
#### `saveComments`
* Saves new or updated comments to your database.
* Params: [SaveCommentResolverRequest](/api-reference/sdk/models/data-models#savecommentresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{ 'success': True, 'statusCode': 200, 'data': { ... } }
```
#### `deleteComment`
* Deletes a comment from your database.
* Params: [DeleteCommentResolverRequest](/api-reference/sdk/models/data-models#deletecommentresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{ 'success': True, 'statusCode': 200, 'data': { ... } }
```
### Reactions
#### `getReactions`
* Fetches reactions from your database for a document.
* Params: [GetReactionResolverRequest](/api-reference/sdk/models/data-models#getreactionresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{
'success': True,
'statusCode': 200,
'data': { 'reactions': [ ... ] }
}
```
#### `saveReactions`
* Saves new or updated reactions to your database.
* Params: [SaveReactionResolverRequest](/api-reference/sdk/models/data-models#savereactionresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{ 'success': True, 'statusCode': 200, 'data': { ... } }
```
#### `deleteReaction`
* Deletes a reaction from your database.
* Params: [DeleteReactionResolverRequest](/api-reference/sdk/models/data-models#deletereactionresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{ 'success': True, 'statusCode': 200, 'data': { ... } }
```
### Users
#### `getUsers`
* Fetches users from your database.
* Params: [GetUserResolverRequest](/api-reference/sdk/models/data-models#getuserresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#saveattachmentresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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)
```
```python theme={null}
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
```
```python theme={null}
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**
```python theme={null}
{ 'success': True, 'statusCode': 200, 'data': { ... } }
```
#### `deleteAttachment`
* Deletes an attachment file from S3 and removes its metadata.
* Params: [DeleteAttachmentResolverRequest](/api-reference/sdk/models/data-models#deleteattachmentresolverrequest)
* Returns: [VeltSelfHostingResponse](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
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)
```
```python theme={null}
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
```
```python theme={null}
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**
```python theme={null}
{ '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](/api-reference/sdk/models/data-models#veltselfhostingresponse)
```python theme={null}
result = sdk.selfHosting.token.getToken(
organizationId='org-123',
userId='user-1',
email='user@example.com',
isAdmin=False
)
```
**Response**
```python theme={null}
{
'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
**SDK Initialization (velt\_sdk.py)**
```python theme={null}
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)**
```python theme={null}
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)**
```python theme={null}
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')
}
```
```python theme={null}
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)
```
```python theme={null}
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`.
```python theme={null}
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](/api-reference/sdk/models/data-models#veltapiresponse).
### Organizations
#### `addOrganizations`
* Creates one or more organizations.
* Params: [AddOrganizationsRequest](/api-reference/sdk/models/data-models#addorganizationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.organization import AddOrganizationsRequest
result = sdk.api.organizations.addOrganizations(
AddOrganizationsRequest(
organizations=[{'organizationId': 'yourOrganizationId', 'organizationName': 'Your Organization Name'}]
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getorganizationsrequest)
* Returns: [GetOrganizationsResponse](/api-reference/sdk/models/data-models#getorganizationsresponse)
```python theme={null}
from velt_py.models.organization import GetOrganizationsRequest
result = sdk.api.organizations.getOrganizations(
GetOrganizationsRequest(
organizationIds=['yourOrganizationId'],
pageSize=1000,
pageToken='pageToken'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updateorganizationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.organization import UpdateOrganizationsRequest
result = sdk.api.organizations.updateOrganizations(
UpdateOrganizationsRequest(
organizations=[{'organizationId': 'yourOrganizationId', 'organizationName': 'Updated Name'}]
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deleteorganizationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.organization import DeleteOrganizationsRequest
result = sdk.api.organizations.deleteOrganizations(
DeleteOrganizationsRequest(organizationIds=['yourOrganizationId1', 'yourOrganizationId2'])
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updateorganizationdisablestaterequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.organization import UpdateOrganizationDisableStateRequest
result = sdk.api.organizations.updateOrganizationDisableState(
UpdateOrganizationDisableStateRequest(
organizationIds=['yourOrganizationId1', 'yourOrganizationId2'],
disabled=True
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addfolderrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.folder import AddFolderRequest
result = sdk.api.folders.addFolder(
AddFolderRequest(
organizationId='yourOrganizationId',
folders=[{
'folderId': 'yourFolderId',
'folderName': 'yourFolderName',
'parentFolderId': 'yourParentFolderId'
}]
)
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Folder created successfully.',
'data': {
'yourFolderId': {
'success': True,
'id': 'yourFolderId',
'message': 'Folder added.'
}
}
}
}
```
#### `getFolders`
* Retrieves folders within an organization.
* Params: [GetFoldersRequest](/api-reference/sdk/models/data-models#getfoldersrequest)
* Returns: [GetFoldersResponse](/api-reference/sdk/models/data-models#getfoldersresponse)
```python theme={null}
from velt_py.models.folder import GetFoldersRequest
result = sdk.api.folders.getFolders(
GetFoldersRequest(organizationId='yourOrganizationId', folderId='yourFolderId')
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updatefolderrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.folder import UpdateFolderRequest
result = sdk.api.folders.updateFolder(
UpdateFolderRequest(
organizationId='yourOrganizationId',
folders=[{'folderId': 'yourFolderId', 'folderName': 'yourFolderName', 'parentFolderId': 'yourParentFolderId'}]
)
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Folder Updated successfully.',
'data': {
'yourFolderId': {
'success': True,
'id': 'yourFolderId',
'message': 'Folder Updated.'
}
}
}
}
```
#### `deleteFolder`
* Deletes a folder.
* Params: [DeleteFolderRequest](/api-reference/sdk/models/data-models#deletefolderrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.folder import DeleteFolderRequest
result = sdk.api.folders.deleteFolder(
DeleteFolderRequest(organizationId='yourOrganizationId', folderId='yourFolderId')
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Folder deleted successfully.',
'data': { 'yourFolderId': {'success': True} }
}
}
```
#### `updateFolderAccess`
* Updates the access type of one or more folders.
* Params: [UpdateFolderAccessRequest](/api-reference/sdk/models/data-models#updatefolderaccessrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.folder import UpdateFolderAccessRequest
result = sdk.api.folders.updateFolderAccess(
UpdateFolderAccessRequest(
organizationId='yourOrganizationId',
folderIds=['yourFolderId'],
accessType='organizationPrivate'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#adddocumentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getdocumentsrequest)
* Returns: [GetDocumentsResponse](/api-reference/sdk/models/data-models#getdocumentsresponse)
```python theme={null}
from velt_py.models.document import GetDocumentsRequest
result = sdk.api.documents.getDocuments(
GetDocumentsRequest(
organizationId='yourOrganizationId',
documentIds=['yourDocumentId'],
folderId='yourFolderId'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updatedocumentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.document import UpdateDocumentsRequest
result = sdk.api.documents.updateDocuments(
UpdateDocumentsRequest(
organizationId='yourOrganizationId',
documents=[{'documentId': 'yourDocumentId', 'documentName': 'Updated Name'}]
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deletedocumentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.document import DeleteDocumentsRequest
result = sdk.api.documents.deleteDocuments(
DeleteDocumentsRequest(
organizationId='yourOrganizationId',
documentIds=['yourDocumentId1', 'yourDocumentId2']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#movedocumentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.document import MoveDocumentsRequest
result = sdk.api.documents.moveDocuments(
MoveDocumentsRequest(
organizationId='yourOrganizationId',
documentIds=['yourDocumentId1', 'yourDocumentId2'],
folderId='target-folder-id'
)
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Documents moved successfully.'
}
}
```
#### `updateDocumentAccess`
* Updates the access type of one or more documents.
* Params: [UpdateDocumentAccessRequest](/api-reference/sdk/models/data-models#updatedocumentaccessrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.document import UpdateDocumentAccessRequest
result = sdk.api.documents.updateDocumentAccess(
UpdateDocumentAccessRequest(
organizationId='yourOrganizationId',
documentIds=['yourDocumentId'],
accessType='organizationPrivate'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updatedocumentdisablestaterequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.document import UpdateDocumentDisableStateRequest
result = sdk.api.documents.updateDocumentDisableState(
UpdateDocumentDisableStateRequest(
organizationId='yourOrganizationId',
documentIds=['yourDocumentId'],
disabled=True
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#migratedocumentsrequest)
* Returns: [MigrateDocumentsResponse](/api-reference/sdk/models/data-models#migratedocumentsresponse)
```python theme={null}
from velt_py.models.document import MigrateDocumentsRequest
result = sdk.api.documents.migrateDocuments(
MigrateDocumentsRequest(
organizationId='yourOrganizationId',
documentId='old-doc-id',
newDocumentId='new-doc-id'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#migratedocumentsstatusrequest)
* Returns: [MigrateDocumentsStatusResponse](/api-reference/sdk/models/data-models#migratedocumentsstatusresponse)
```python theme={null}
from velt_py.models.document import MigrateDocumentsStatusRequest
result = sdk.api.documents.migrateDocumentsStatus(
MigrateDocumentsStatusRequest(
organizationId='yourOrganizationId',
migrationId='yourMigrationId'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addusersrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getusersrequest)
* Returns: [GetUsersResponse](/api-reference/sdk/models/data-models#getusersresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updateusersrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deleteusersrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.user_api import DeleteUsersRequest
result = sdk.api.users.deleteUsers(
DeleteUsersRequest(
organizationId='yourOrganizationId',
userIds=['yourUserId1', 'yourUserId2']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addusergroupsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.user_group import AddUserGroupsRequest
result = sdk.api.userGroups.addUserGroups(
AddUserGroupsRequest(
organizationId='yourOrganizationId',
organizationUserGroups=[{'groupId': 'yourGroupId', 'groupName': 'Engineering'}],
createOrganization=True
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#adduserstogrouprequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.user_group import AddUsersToGroupRequest
result = sdk.api.userGroups.addUsersToGroup(
AddUsersToGroupRequest(
organizationId='yourOrganizationId',
organizationUserGroupId='yourGroupId',
userIds=['yourUserId1', 'yourUserId2']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deleteusersfromgrouprequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.user_group import DeleteUsersFromGroupRequest
result = sdk.api.userGroups.deleteUsersFromGroup(
DeleteUsersFromGroupRequest(
organizationId='yourOrganizationId',
organizationUserGroupId='yourGroupId',
userIds=['yourUserId1'],
deleteAll=False
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addnotificationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Notification added successfully.',
'data': {
'success': True,
'message': 'Notification added successfully.'
}
}
}
```
#### `getNotifications`
* Retrieves notifications for a user or document.
* Params: [GetNotificationsRequest](/api-reference/sdk/models/data-models#getnotificationsrequest)
* Returns: [GetNotificationsResponse](/api-reference/sdk/models/data-models#getnotificationsresponse)
```python theme={null}
from velt_py.models.notification_api import GetNotificationsRequest
result = sdk.api.notifications.getNotifications(
GetNotificationsRequest(
organizationId='yourOrganizationId',
userId='user-2',
pageSize=10,
order='desc'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updatenotificationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.notification_api import UpdateNotificationsRequest
result = sdk.api.notifications.updateNotifications(
UpdateNotificationsRequest(
organizationId='yourOrganizationId',
notifications={'5471488637912692': {'isRead': True}}
)
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Notification(s) updated successfully.',
'data': {
'5471488637912692': {
'success': True,
'message': 'Notification updated.'
}
}
}
}
```
#### `deleteNotifications`
* Deletes one or more notifications.
* Params: [DeleteNotificationsRequest](/api-reference/sdk/models/data-models#deletenotificationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.notification_api import DeleteNotificationsRequest
result = sdk.api.notifications.deleteNotifications(
DeleteNotificationsRequest(
organizationId='yourOrganizationId',
notificationIds=['8955243231506071']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getnotificationconfigrequest)
* Returns: [GetNotificationConfigResponse](/api-reference/sdk/models/data-models#getnotificationconfigresponse)
```python theme={null}
from velt_py.models.notification_api import GetNotificationConfigRequest
result = sdk.api.notifications.getNotificationConfig(
GetNotificationConfigRequest(
organizationId='org1',
userId='USER_ID1'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#setnotificationconfigrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addcommentannotationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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': 'Sample Comment
',
'from': {'userId': 'yourUserId', 'name': 'yourUserName', 'email': 'yourUserEmail'}
}]
}]
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getcommentannotationsrequest)
* Returns: [GetCommentAnnotationsResponse](/api-reference/sdk/models/data-models#getcommentannotationsresponse)
```python theme={null}
from velt_py.models.comment_annotation_api import GetCommentAnnotationsRequest
result = sdk.api.commentAnnotations.getCommentAnnotations(
GetCommentAnnotationsRequest(
organizationId='yourOrganizationId',
documentId='yourDocumentId',
statusIds=['OPEN'],
pageSize=10
)
)
```
**Response**
```python theme={null}
{
'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': 'This is a sample comment text.
',
'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](/api-reference/sdk/models/data-models#getcommentannotationscountrequest)
* Returns: [GetCommentAnnotationsCountResponse](/api-reference/sdk/models/data-models#getcommentannotationscountresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updatecommentannotationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deletecommentannotationsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.comment_annotation_api import DeleteCommentAnnotationsRequest
result = sdk.api.commentAnnotations.deleteCommentAnnotations(
DeleteCommentAnnotationsRequest(
organizationId='yourOrganizationId',
documentId='yourDocumentId',
annotationIds=['yourAnnotationId1', 'yourAnnotationId2']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addcommentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Comment(s) added successfully.',
'data': [778115]
}
}
```
#### `getComments`
* Retrieves individual comments inside an annotation.
* Params: [GetCommentsRequest](/api-reference/sdk/models/data-models#getcommentsrequest)
* Returns: [GetCommentsResponse](/api-reference/sdk/models/data-models#getcommentsresponse)
```python theme={null}
from velt_py.models.comment_annotation_api import GetCommentsRequest
result = sdk.api.commentAnnotations.getComments(
GetCommentsRequest(
organizationId='yourOrganizationId',
documentId='yourDocumentId',
annotationId='yourAnnotationId',
userIds=['yourUserId']
)
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Comments retrieved successfully.',
'data': [
{
'commentId': 123456,
'type': 'text',
'commentText': 'This is a sample comment text.',
'commentHtml': 'This is a sample comment text.
',
'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](/api-reference/sdk/models/data-models#updatecommentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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': 'Updated text
'}
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deletecommentsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addactivitiesrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getactivitiesrequest)
* Returns: [GetActivitiesResponse](/api-reference/sdk/models/data-models#getactivitiesresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updateactivitiesrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deleteactivitiesrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.activity_api import DeleteActivitiesRequest
result = sdk.api.activities.deleteActivities(
DeleteActivitiesRequest(
organizationId='org-123',
activityIds=['activity-001', 'activity-002']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addpermissionsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Permissions added successfully.'
}
}
```
#### `getPermissions`
* Retrieves permissions for one or more users.
* Params: [GetPermissionsRequest](/api-reference/sdk/models/data-models#getpermissionsrequest)
* Returns: [GetPermissionsResponse](/api-reference/sdk/models/data-models#getpermissionsresponse)
```python theme={null}
from velt_py.models.access_control import GetPermissionsRequest
result = sdk.api.accessControl.getPermissions(
GetPermissionsRequest(
organizationId='org1',
userIds=['1.1'],
documentIds=['document1']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#removepermissionsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Permissions removed successfully.'
}
}
```
#### `generateSignature`
* Generates a signed payload for Velt's Permission Provider flow.
* Params: [GenerateSignatureRequest](/api-reference/sdk/models/data-models#generatesignaturerequest)
* Returns: [GenerateSignatureResponse](/api-reference/sdk/models/data-models#generatesignatureresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#generatetokenrequest)
* Returns: [GenerateTokenResponse](/api-reference/sdk/models/data-models#generatetokenresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#addcrdtdatarequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'CRDT data added successfully.'
}
}
```
#### `getCrdtData`
* Retrieves CRDT data for one or all editors on a document.
* Params: [GetCrdtDataRequest](/api-reference/sdk/models/data-models#getcrdtdatarequest)
* Returns: [GetCrdtDataResponse](/api-reference/sdk/models/data-models#getcrdtdataresponse)
```python theme={null}
from velt_py.models.crdt import GetCrdtDataRequest
result = sdk.api.crdt.getCrdtData(
GetCrdtDataRequest(
organizationId='yourOrganizationId',
documentId='yourDocumentId',
editorId='my-collab-note'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updatecrdtdatarequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'CRDT data updated successfully.'
}
}
```
### Presence
#### `addPresence`
* Adds users to a document's presence list.
* Params: [AddPresenceRequest](/api-reference/sdk/models/data-models#addpresencerequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Presence added successfully.',
'data': { 'success': True }
}
}
```
#### `updatePresence`
* Updates presence status for one or more users on a document.
* Params: [UpdatePresenceRequest](/api-reference/sdk/models/data-models#updatepresencerequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Presence updated successfully.',
'data': { 'success': True }
}
}
```
#### `deletePresence`
* Removes users from a document's presence list.
* Params: [DeletePresenceRequest](/api-reference/sdk/models/data-models#deletepresencerequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#broadcasteventrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getrecordingsrequest)
* Returns: [GetRecordingsResponse](/api-reference/sdk/models/data-models#getrecordingsresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#askairequest)
* Returns: [AskAiResponse](/api-reference/sdk/models/data-models#askairesponse)
```python theme={null}
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**
```python theme={null}
{
'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.
### GDPR
#### `deleteAllUserData`
* Requests deletion of all data associated with one or more users.
* Params: [DeleteAllUserDataRequest](/api-reference/sdk/models/data-models#deletealluserdatarequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.gdpr import DeleteAllUserDataRequest
result = sdk.api.gdpr.deleteAllUserData(
DeleteAllUserDataRequest(
userIds=['user-1', 'user-2'],
organizationIds=['org-123']
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getalluserdatarequest)
* Returns: [GetAllUserDataResponse](/api-reference/sdk/models/data-models#getalluserdataresponse)
```python theme={null}
from velt_py.models.gdpr import GetAllUserDataRequest
result = sdk.api.gdpr.getAllUserData(
GetAllUserDataRequest(
organizationId='org-123',
userId='user-1',
pageToken='next-page-token'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getdeleteuserdatastatusrequest)
* Returns: [GetDeleteUserDataStatusResponse](/api-reference/sdk/models/data-models#getdeleteuserdatastatusresponse)
```python theme={null}
from velt_py.models.gdpr import GetDeleteUserDataStatusRequest
result = sdk.api.gdpr.getDeleteUserDataStatus(
GetDeleteUserDataStatusRequest(jobId='job-id-from-delete-call')
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Data fetched successfully.',
'data': {
'isDeleteCompleted': True,
'tasksLeft': 0,
'lastTaskCompletedTime': 1748972106739
}
}
}
```
### Workspace
#### `createWorkspace`
* Creates a new workspace.
* Params: [CreateWorkspaceRequest](/api-reference/sdk/models/data-models#createworkspacerequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.workspace import CreateWorkspaceRequest
result = sdk.api.workspace.createWorkspace(
CreateWorkspaceRequest(
ownerEmail='owner@example.com',
workspaceName='My Workspace',
name='John Doe'
)
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getworkspacerequest)
* Returns: [GetWorkspaceResponse](/api-reference/sdk/models/data-models#getworkspaceresponse)
```python theme={null}
from velt_py.models.workspace import GetWorkspaceRequest
result = sdk.api.workspace.getWorkspace(GetWorkspaceRequest())
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#createapikeyrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updateapikeyrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.workspace import UpdateApiKeyRequest
result = sdk.api.workspace.updateApiKey(
UpdateApiKeyRequest(apiKey='velt_api_key_1', apiKeyName='Renamed Key')
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'API key updated successfully.',
'data': None
}
}
```
#### `getApiKeys`
* Lists all API keys in the workspace.
* Params: [GetApiKeysRequest](/api-reference/sdk/models/data-models#getapikeysrequest)
* Returns: [GetApiKeysResponse](/api-reference/sdk/models/data-models#getapikeysresponse)
```python theme={null}
from velt_py.models.workspace import GetApiKeysRequest
result = sdk.api.workspace.getApiKeys(
GetApiKeysRequest(pageSize=50, pageToken='next-page-token')
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getapikeymetadatarequest)
* Returns: [GetApiKeyMetadataResponse](/api-reference/sdk/models/data-models#getapikeymetadataresponse)
```python theme={null}
from velt_py.models.workspace import GetApiKeyMetadataRequest
result = sdk.api.workspace.getApiKeyMetadata(GetApiKeyMetadataRequest())
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#resetauthtokenrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.workspace import ResetAuthTokenRequest
result = sdk.api.workspace.resetAuthToken(
ResetAuthTokenRequest(apiKey='velt_api_key_1')
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getauthtokensrequest)
* Returns: [GetAuthTokensResponse](/api-reference/sdk/models/data-models#getauthtokensresponse)
```python theme={null}
from velt_py.models.workspace import GetAuthTokensRequest
result = sdk.api.workspace.getAuthTokens(
GetAuthTokensRequest(apiKey='velt_api_key_1')
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#adddomainsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.workspace import AddDomainsRequest
result = sdk.api.workspace.addDomains(
AddDomainsRequest(domains=['google.com', '*.firebase.com'])
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#deletedomainsrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.workspace import DeleteDomainsRequest
result = sdk.api.workspace.deleteDomains(
DeleteDomainsRequest(domains=['google.com', '*.firebase.com'])
)
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getdomainsrequest)
* Returns: [GetDomainsResponse](/api-reference/sdk/models/data-models#getdomainsresponse)
```python theme={null}
from velt_py.models.workspace import GetDomainsRequest
result = sdk.api.workspace.getDomains(GetDomainsRequest())
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#getemailstatusrequest)
* Returns: [GetEmailStatusResponse](/api-reference/sdk/models/data-models#getemailstatusresponse)
```python theme={null}
from velt_py.models.workspace import GetEmailStatusRequest
result = sdk.api.workspace.getEmailStatus(
GetEmailStatusRequest(ownerEmail='owner@example.com')
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Email verified and workspace reactivated',
'data': { 'verified': True }
}
}
```
#### `sendLoginLink`
* Sends a login link email to a user.
* Params: [SendLoginLinkRequest](/api-reference/sdk/models/data-models#sendloginlinkrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
from velt_py.models.workspace import SendLoginLinkRequest
result = sdk.api.workspace.sendLoginLink(
SendLoginLinkRequest(email='user@example.com', continueUrl='https://app.example.com/dashboard')
)
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Login link sent successfully.',
'data': None
}
}
```
#### `getEmailConfig`
* Retrieves the workspace's email service configuration.
* Params: [GetEmailConfigRequest](/api-reference/sdk/models/data-models#getemailconfigrequest)
* Returns: [GetEmailConfigResponse](/api-reference/sdk/models/data-models#getemailconfigresponse)
```python theme={null}
from velt_py.models.workspace import GetEmailConfigRequest
result = sdk.api.workspace.getEmailConfig(GetEmailConfigRequest())
```
**Response**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#updateemailconfigrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Email configuration updated successfully.',
'data': None
}
}
```
#### `getWebhookConfig`
* Retrieves the workspace's webhook configuration.
* Params: [GetWebhookConfigRequest](/api-reference/sdk/models/data-models#getwebhookconfigrequest)
* Returns: [GetWebhookConfigResponse](/api-reference/sdk/models/data-models#getwebhookconfigresponse)
```python theme={null}
from velt_py.models.workspace import GetWebhookConfigRequest
result = sdk.api.workspace.getWebhookConfig(GetWebhookConfigRequest())
```
**Response**
```python theme={null}
{
'result': {
'status': 'success',
'message': 'Webhook configuration retrieved successfully.',
'data': {
'useWebhookService': False,
'webhookServiceConfig': {
'authToken': '',
'rawNotificationUrl': '',
'processedNotificationUrl': ''
}
}
}
}
```
#### `updateWebhookConfig`
* Updates the workspace's webhook configuration.
* Params: [UpdateWebhookConfigRequest](/api-reference/sdk/models/data-models#updatewebhookconfigrequest)
* Returns: [VeltApiResponse](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
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**
```python theme={null}
{
'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](/api-reference/sdk/models/data-models#veltapiresponse)
```python theme={null}
result = sdk.api.token.getToken(
organizationId='org-123',
userId='user-1',
email='user@example.com',
isAdmin=False
)
```
**Response**
```python theme={null}
{
'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) |
```python theme={null}
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
## Resources
* [Velt-Py PyPI Package](https://pypi.org/project/velt-py)
* [Self-Host Data Documentation](/self-host-data/overview)