Python SDK (velt-py) Changelog

Release notes for the velt-py Python SDK for self-hosting

Libraries

• velt-py

​

Python SDK (velt-py) v0.1.15

August 10, 2026

New Features

• [REST API]: New agent filters on comment annotations. getCommentAnnotations accepts agentId, executionId, agentType, agentSource, agentSuggestions, and agentComments to scope a listing to agent-authored annotations (supply at most one per request), and deleteCommentAnnotations accepts agentId, agentUrls, and agentSuggestions, which combine so a crawl can delete “this agent’s still-pending suggestions for these pages” without affecting a concurrent batch. Agent filtering requires advanced queries on your workspace; when unavailable the API fails closed rather than widening to a document-wide delete. Also adds order, statusId, resolvedBy, mentionedUserIds, includeMetadata, and includePageInfo read filters. Learn more →

• [REST API]: New per-execution agent options. runExecution accepts deviceType ('mobile' or 'desktop', defaults to desktop) to choose the emulated device, annotationVisibility ('public' or 'private', defaults to private) to control who can see the annotations the run creates, and an aiConfig override dict (provider, model, defaultModels, maxToolTurns) to pin the model for a single run. Learn more →

• [REST API]: New filters on getDocumentsCount. Accepts the same list of {key, operator, value} dicts as getDocuments (up to 10; keys auto-prefixed with metadata. unless already prefixed). Cannot be combined with excludeFolderDocs. When filters are sent the response includes filtersApplied — a False value means the filtered aggregate failed and count is an unfiltered fallback. Learn more →

• [REST API]: New includeRules on searchKnowledge. Set it to True to additionally search the workspace’s extracted-rules corpus and merge those hits with knowledge-chunk results; each result then carries a kind of 'chunk' or 'rule', and rule hits also carry ruleId and an optional category. Omitting it returns the previous chunk-only shape, and limit becomes the combined cap across both corpora. Learn more →

• [REST API]: New purge flag on the workflow delete-definition request hard-deletes a definition and its version snapshots instead of leaving a tombstone. Both paths free the definition ID for re-creation. Workflow definitions also document the notification-node, scheduled-trigger, and installable-app-trigger (GitHub App / Vercel Integration, including payload filters) shapes accepted inside nodes and triggers. Learn more →

• [REST API]: New name and permissions parameters on getAuthToken, alongside the existing isAdmin. Adds provisioning fields to CreateApiKeyRequest (persistenceDBRegion, realtimeDBRegion, isSuperWorkspace, platform, workspaceId, enablePrivateComments, requireAutoOrgUser, useNotificationService, setDefaultEmailTriggers, setDefaultNotificationTriggers) and expiresInMs to CreateWorkspaceRequest. Learn more →

• [REST API]: New fields across several services — veltUserIds, veltAllOrganizations, and uniqueId on get-all-user-data; skipResourceExistenceValidation on get-permissions; pageSize, pageToken, and rootFoldersOnly on folders; displayBodyMessageTemplate, displayBodyMessageTemplateData, isCrossOrganizationEnabled, metadata, notifyUsers, and location on notifications; type and isServerIds on get-CRDT-data; merge and orderByCommentViews on documents. Learn more →

• [Self Hosting]: New resolveUserIdsByEmail resolver on UserService, with a ResolveUserIdsByEmailRequest model. Resolves a list of email addresses to an {email: userId} map, honouring custom user_schema field mappings. Repeated emails are de-duplicated and blank or None entries are dropped; addresses that do not match are simply absent from the returned map. Learn more →

Improvements

• [REST API]: The deprecated loops field on workflow definition requests can no longer break a request. Loop regions are no longer part of the workflow definition contract, and the API rejects any definition that carries them, so loops is now stripped from the payload before send — a request that sets it succeeds instead of failing. Setting it to a non-None value raises a DeprecationWarning so the value is not dropped silently; leaving it unset (or explicitly None) is completely silent. Express loops as edges instead: an on: 'reject' back-edge carrying a loop object, for example {"from": "review", "to": "draft", "on": "reject", "loop": {"maxIterations": 3}}. Learn more →

​

Python SDK (velt-py) v0.1.14

June 19, 2026

New Features

• [Self Hosting]: New pluggable, fail-closed sdk.selfHosting.verifyToken helper authenticates the credential the Velt frontend forwards to endpoint-based self-hosting resolvers. Opt in via a resolver_auth config block; it supports a built-in JWT/JWKS verifier (HS256/RS256/ES256 with algorithm pinning, HTTPS-only JWKS, claim enforcement, leeway, opt-in exp requirement) and a custom-callback escape hatch. It returns a structured VerifyTokenResult and never raises for a verification outcome. Adds the optional velt-py[auth] extra (PyJWT>=2.8.0, cryptography>=42.0.0) and new exports VerifyTokenResult and ResolverAuthService. Learn more →

• [Self Hosting]: New 14-member CommentResolverSaveEvent (str, Enum) covers additional comment-resolver save events (status change, priority change, assign, approve, comment-level reactions, subscribe/unsubscribe, and more) the frontend can opt into sending via ResolverConfig.additionalSaveEvents. SaveCommentResolverRequest.event is widened to Optional[Union[ResolverActions, CommentResolverSaveEvent, str]] and stays fully additive — every existing ResolverActions value still parses to the same member. Exported from velt_py and velt_py.models. Learn more →

• [Self Hosting]: New optional SaveCommentResolverRequest.targetComment: Optional[PartialComment] field carries the comment the action occurred on (resolved by the frontend from commentId). from_dict parses it fail-open; it is request context for your handler only and saveComments never persists it. Learn more →

​

Python SDK (velt-py) v0.1.12

June 16, 2026

Bug Fixes

• [Self Hosting]: Legacy reaction documents stored under the old user key are read transparently. from_dict() accepts either from or the legacy user key (from wins when both are present) and populates from_, while to_dict() always emits from. No data migration is needed. Learn more →

• [Self Hosting]: The self-hosting package now exports all wired services. RecorderService, NotificationService, and ActivityService are now importable from velt_py.services.self_hosting and listed in its __all__. Learn more →

​

Python SDK (velt-py) v0.1.11

June 16, 2026

New Features

• [REST API]: New agents service (sdk.api.agents) for managing AI agents, versions, executions, prompt tooling, and agent groups (24 methods). Learn more →

• [REST API]: New memory service (sdk.api.memory) for semantic search, judgments, knowledge ingestion, reviewer profiles/patterns/stats, and alerts (24 methods). Learn more →

• [REST API]: New workflow service (sdk.api.workflow) for Approval Engine / workflow orchestration, covering definitions, executions, lifecycle events, and step resolution (14 methods). Learn more →

• [REST API]: users service additions for user invitations (invite/respond/list), counts, and document-user queries; getUsers gains optional includeInvolvedDocuments and searchKey filters. Learn more →

• [REST API]: documents service adds getDocumentsCount, which can optionally exclude folder documents or scope the count to a specific folder. Learn more →

• [REST API]: crdt service adds deleteCrdtData, which targets specific editorIds or deletes all editors for a document when omitted. Learn more →

• [REST API]: workspace service adds 19 new methods covering domain requests, API key configuration/copy, notification/permission-provider/activity configs, and advanced (Svix) webhook endpoint management. Learn more →

Improvements

• [REST API]: New opt-in filter_unknown_fields keyword (default False) on the add/update methods of commentAnnotations, activities, and notifications filters request entity collections to only the fields the Velt API accepts, dropping unknown top-level custom keys. It applies to top-level fields only (nested open-typed fields pass through whole) and fails open, never blocking a write. Backed by a new velt_py.models.field_allowlists module.

Bug Fixes

• [REST API]: sdk.api.workspace.getApiKeyMetadata now targets the canonical /v2/workspace/apikeyconfig/get endpoint (previously /v2/workspace/apikeymetadata/get, which remains a legacy alias). No call-site change is required — the method signature is unchanged.

​

Python SDK (velt-py) v0.1.10

May 19, 2026

New Features

• [Self Hosting]: PartialCommentAnnotation now exposes from (comment author), assignedTo, targetTextRange, and resolvedByUserId as first-class typed fields. These four keys previously fell through silently via extra_fields. Learn more →

• [Self Hosting]: New PartialTargetTextRange dataclass (exported from velt_py.models) represents the selected text snippet a comment annotation is anchored to. Learn more →

Improvements

• [Self Hosting]: BaseMetadata now models sdkVersion and documentMetadata, which were previously dropped silently; self-hosted Mongo writes now preserve both fields.

• [Self Hosting]: Introduced an UNSET sentinel on resolvedByUserId to distinguish “field absent from payload” (no Mongo write) from “explicit null” (the frontend’s unresolve action — writes null to Mongo).

Bug Fixes

None.

​

Python SDK (velt-py) v0.1.9

April 20, 2026

New Features

• [REST API Backend]: The sdk.api.* namespace is now available, introducing a REST API backend for the Python SDK with feature parity with the Velt Node SDK. Learn more →

• [REST API Services]: 17 services are included: organizations, folders, documents, users, userGroups, notifications, commentAnnotations, activities, accessControl, crdt, presence, livestate, recordings, rewriter, gdpr, workspace, and token.

• [Typed Request Dataclasses]: Every sdk.api.* method accepts a typed @dataclass request object (e.g., AddOrganizationsRequest) and returns the raw Velt API response without local reshaping or validation.

• [camelCase Method Names]: All sdk.api.* method names are camelCase and match the JavaScript/Node SDK one-to-one.

• [Custom Error Classes]: Three new error classes are available: VeltValidationError, VeltTokenError, and VeltApiError, all extending the base VeltSDKError.

• [Environment Variable Support]: The SDK reads VELT_API_KEY, VELT_AUTH_TOKEN, VELT_WORKSPACE_ID, and VELT_WORKSPACE_AUTH_TOKEN from the environment for credential configuration.

• [PyPI Distribution]: The package is published to PyPI as velt-py. Requires Python 3.8+; the requests library is installed automatically as a dependency.