velt-py 0.1.13

Python SDK for integrating Velt comments, reactions, attachments, and user management into Django applications

Velt Python SDK

Velt is an SDK to add collaborative features to your product within minutes. Example: Comments like Figma, Frame.io, Google Docs or Sheets, Recording like Loom, Huddles like Slack, and much more.

velt-py is the official backend SDK for Velt. Use it to power a self-hosted Velt backend or to call Velt's REST APIs directly from any Python service.

The 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 (sdk.selfHosting.*) simplifies backend implementation by up to 90%. Pass your DB and storage configs to the SDK, call the relevant method with the raw frontend request payload, and return the response directly to the client.
• REST API (sdk.api.*) provides fully-typed @dataclass request objects across all Velt REST services, returning raw Velt API responses. No database or AWS configuration needed.

Features

With Velt you can add powerful collaboration features to your backend extremely fast:

• Comments like Figma, Frame.io, Google Docs, Sheets and more
• Recording like Loom (audio, video, screen)
• Huddle like Slack (audio, video, screensharing)
• In-app and off-app notifications
• @mentions and assignment
• Presence, Cursors, Live Selection
• Live state sync and multiplayer editing with conflict resolution (CRDT)
• Activities, access control, GDPR data tooling, and AI-powered agents & workflows
• ... and so much more

Installation

pip install velt-py

Requirements

• Python 3.8+
• MongoDB 6+ (Percona Server or MongoDB Atlas) for self-hosting
• requests for REST API calls (installed automatically)
• pymongo and boto3 for the self-hosting backend (MongoDB + optional S3 attachments)

Quick Start

Initialize the SDK

Self-hosting (MongoDB + optional AWS S3):

from velt_py import VeltSDK

sdk = VeltSDK.initialize({
    'database': {
        'connection_string': 'mongodb+srv://user:[e-mail]/velt-db',
        # Or pass individual components:
        # 'host': 'localhost:27017',
        # 'username': 'your-username',
        # 'password': 'your-password',
        # 'auth_database': 'admin',
        # 'database_name': 'velt-db',
    },
    'apiKey': 'YOUR_VELT_API_KEY',       # or set VELT_API_KEY
    'authToken': 'YOUR_VELT_AUTH_TOKEN', # or set VELT_AUTH_TOKEN
})

REST API only (no database needed):

from velt_py import VeltSDK

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

# All sdk.api.* services are now available
result = sdk.api.organizations.getOrganizations(
    GetOrganizationsRequest(organizationIds=['org-123'])
)

Self-hosting example

Each self-hosting method takes a single typed resolver-request object — build it from the incoming frontend JSON with from_dict(data) and return the result straight to the client:

from velt_py import GetCommentResolverRequest

result = sdk.selfHosting.comments.getComments(
    GetCommentResolverRequest.from_dict(data)
)

REST API example

Each sdk.api.* method takes a single typed request dataclass:

from velt_py.models.comment_annotation_api import AddCommentAnnotationsRequest

sdk.api.commentAnnotations.addCommentAnnotations(
    AddCommentAnnotationsRequest(
        organizationId='org-123',
        documentId='doc-1',
        commentAnnotations=[{
            'location': {'id': 'section-1', 'locationName': 'Introduction'},
            'commentData': [{
                'commentText': 'This needs review',
                'from': {'userId': 'user-1', 'name': 'John Doe', 'email': '[e-mail]'},
            }],
        }],
    )
)

Framework integration

Initialize the SDK once and reuse it across requests. For example, with FastAPI:

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()
    result = sdk.selfHosting.comments.getComments(GetCommentResolverRequest.from_dict(data))
    return JSONResponse(content=result, status_code=result.get('statusCode', 200))

See the Python SDK documentation for Django, Flask, and FastAPI integration guides.

Shutdown

Call sdk.close() during graceful shutdown to release the database connection pool:

sdk.close()

Documentation

• Read the Python SDK documentation for the full setup guide, configuration reference, and a complete list of sdk.selfHosting.* and sdk.api.* methods with request/response examples.
• Browse the broader Velt documentation for guides and frontend SDK references.
• velt-py on PyPI

Use cases

• Explore use cases to learn how collaboration could look on your product.
• Figma Template: visualize what collaboration features could look like on your product.

Releases

• See the latest changes.

Security

• Velt is SOC2 Type 2 and HIPAA compliant. Learn more

Community

• X: updates, announcements, and general Velt tips.
• Discord: ask questions and share tips.

License

MIT

Support

For issues and questions, contact [e-mail] or visit docs.velt.dev.