> ## 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 SDK (velt-py) Changelog

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

### Libraries

* `velt-py`

<Update label="Python SDK (velt-py) v0.1.15" description="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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  ### 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 →](/docs/backend-sdks/python)
</Update>

<Update label="Python SDK (velt-py) v0.1.14" description="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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)
</Update>

<Update label="Python SDK (velt-py) v0.1.12" description="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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)
</Update>

<Update label="Python SDK (velt-py) v0.1.11" description="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 →](/docs/backend-sdks/python)

  * \[**REST API**]: New `memory` service (`sdk.api.memory`) for semantic search, judgments, knowledge ingestion, reviewer profiles/patterns/stats, and alerts (24 methods). [Learn more →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  * \[**REST API**]: `documents` service adds `getDocumentsCount`, which can optionally exclude folder documents or scope the count to a specific folder. [Learn more →](/docs/backend-sdks/python)

  * \[**REST API**]: `crdt` service adds `deleteCrdtData`, which targets specific `editorIds` or deletes all editors for a document when omitted. [Learn more →](/docs/backend-sdks/python)

  * \[**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 →](/docs/backend-sdks/python)

  ### 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.
</Update>

<Update label="Python SDK (velt-py) v0.1.10" description="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 →](/docs/backend-sdks/python)

  * \[**Self Hosting**]: New `PartialTargetTextRange` dataclass (exported from `velt_py.models`) represents the selected text snippet a comment annotation is anchored to. [Learn more →](/docs/backend-sdks/python)

  ### 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.
</Update>

<Update label="Python SDK (velt-py) v0.1.9" description="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 →](/docs/backend-sdks/python)

  * \[**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.
</Update>