From cccaa85d31ae54daf91cf291dd9c872d98dc9233 Mon Sep 17 00:00:00 2001 From: Rakesh Date: Fri, 5 Jun 2026 19:21:50 -0700 Subject: [PATCH 1/4] docs(rest-apis): add and update v2 comments-feature and workspace API references Port changes from raghul/agent-docs (PR #168) scoped to: - api-reference/rest-apis/v2/comments-feature - api-reference/rest-apis/v2/workspace Includes new activity/apikey/notification/permission-provider config endpoints and renames apikeymetadata-get to permissionproviderconfig-get. Co-authored-by: Cursor --- .../add-comment-annotations.mdx | 211 ++++++++++++++++++ .../get-comment-annotations-v2.mdx | 62 ++++- .../comments/add-comments.mdx | 103 +++++++++ .../v2/workspace/activityconfig-get.mdx | 89 ++++++++ .../v2/workspace/activityconfig-update.mdx | 122 ++++++++++ .../rest-apis/v2/workspace/apikey-create.mdx | 12 +- .../rest-apis/v2/workspace/apikey-update.mdx | 6 +- .../v2/workspace/apikeyconfig-get.mdx | 109 +++++++++ .../v2/workspace/apikeyconfig-update.mdx | 136 +++++++++++ .../rest-apis/v2/workspace/apikeys-get.mdx | 6 +- .../v2/workspace/authtoken-reset.mdx | 6 +- .../rest-apis/v2/workspace/authtokens-get.mdx | 6 +- .../v2/workspace/emailconfig-update.mdx | 28 ++- api-reference/rest-apis/v2/workspace/get.mdx | 6 +- .../v2/workspace/notificationconfig-get.mdx | 103 +++++++++ .../workspace/notificationconfig-update.mdx | 172 ++++++++++++++ ...t.mdx => permissionproviderconfig-get.mdx} | 32 +-- .../permissionproviderconfig-update.mdx | 102 +++++++++ .../v2/workspace/webhookconfig-get.mdx | 4 + .../v2/workspace/webhookconfig-update.mdx | 36 ++- 20 files changed, 1308 insertions(+), 43 deletions(-) create mode 100644 api-reference/rest-apis/v2/workspace/activityconfig-get.mdx create mode 100644 api-reference/rest-apis/v2/workspace/activityconfig-update.mdx create mode 100644 api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx create mode 100644 api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx create mode 100644 api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx create mode 100644 api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx rename api-reference/rest-apis/v2/workspace/{apikeymetadata-get.mdx => permissionproviderconfig-get.mdx} (57%) create mode 100644 api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx index 74af7e1db..bd8d35908 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations.mdx @@ -36,6 +36,14 @@ Use this API to add comment annotations to a document within an organization. Document ID + + If set to true, a new organization will be created (if it doesn't exist) before the annotation is added. + + + + If set to true, a new document will be created (if it doesn't exist) before the annotation is added. + + When enabled, verifies the user has access to the document before creating comment annotations. This ensures annotations respect document access permissions configured via Access Control or Permission Provider. @@ -150,6 +158,71 @@ Use this API to add comment annotations to a document within an organization. + + + Marks this comment as agent-authored (an agent finding or an agent reply). V2 only. When set, the server stamps `sourceType: "agent"` on the comment. When set on the root comment (`commentData[0]`), the server also generates the annotation-level agent block and stamps `sourceType: "agent"` on the annotation. Discriminated on `agentSource`. + + + Origin of the agent. Must be one of: `velt` or `external`. + + + Agent ID. Required when `agentSource` is `velt` (a built-in agent like `spell-check`, or a custom agent ID that is verified server-side). Optional and opaque (never validated) when `agentSource` is `external`. + + + Execution / run ID for this agent invocation. + + + Display name for the agent. **Required when `agentSource` is `external`** (the only source of truth for an external agent's name). Not used for `velt` agents (their name is resolved server-side). + + + Page URL associated with the finding. + + + Finding details produced by the agent. Additional custom fields are preserved. + + + Short finding title. + + + Finding description. + + + Severity of the finding. Must be one of: `critical`, `high`, `medium`, `low`, or `info`. + + + Unique identifier for the finding. + + + Type of finding. Must be one of: `text`, `pin`, or `page`. + + + Custom issue classification. + + + Confidence score for the finding. Integer between 0 and 100. + + + Suggested change in plain text. + + + Suggested fix for the finding. + + + Relevant HTML snippet for the finding. + + + CSS/HTML selector pointing to the finding location. + + + Provenance of the rule that triggered the finding. Must be one of: `instructions` or `knowledge`. + + + Knowledge section that triggered the finding. + + + + + @@ -223,6 +296,36 @@ Use this API to add comment annotations to a document within an organization. + + + Annotation kind. Must be one of: `comment` or `suggestion`. This is the source of truth for the suggestion classification; agent-produced findings should set `suggestion`. Defaults to `comment` when omitted. + + + + Caller-driven comment classification. Must be one of: `manual` or `chart`. Defaults to `manual` when omitted. + + + The legacy value `commentType: "suggestion"` is still accepted and preserved for backward compatibility, but it no longer drives the suggestion classification. Use the annotation-level `type: "suggestion"` field instead. + + + + + Controls who can see the annotation. Discriminated on `type`. When omitted, the annotation defaults to `public`. + + + Visibility type. Must be one of: `public`, `organizationPrivate`, or `restricted`. + - `public`: Visible to everyone. + - `organizationPrivate`: Visible only to users in the specified organization. Requires `organizationId`. + - `restricted`: Visible only to the specified users (private comment). Requires `userIds`. + + + Organization ID whose users can see the annotation. Required when `type` is `organizationPrivate`. + + + User IDs allowed to see the annotation. Required (non-empty) when `type` is `restricted`. + + + @@ -393,6 +496,114 @@ When `verifyUserPermissions` is enabled, the API verifies the user has access to } ``` +#### Add an agent suggestion (finding) + +Set `type: "suggestion"` and attach an `agent` block to the root comment (`commentData[0]`). The server generates the annotation-level agent block and stamps `sourceType: "agent"`. + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "type": "suggestion", + "commentData": [ + { + "commentText": "Heading has a spelling mistake: 'Welcom' should be 'Welcome'.", + "from": { + "userId": "spell-check", + "name": "Spell Check Agent" + }, + "agent": { + "agentSource": "velt", + "agentId": "spell-check", + "executionId": "exec_123", + "url": "https://example.com/design-mockup-v2", + "reason": { + "title": "Spelling error", + "description": "The word 'Welcom' is misspelled.", + "severity": "low", + "findingType": "text", + "confidence": 98, + "suggestedFix": "Welcome", + "source": "instructions" + } + } + } + ] + } + ] + } +} +``` + +To attach a finding from an agent run through your own framework, use `agentSource: "external"` and supply your own `agentName` (and optionally `agentId` / `executionId`): + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "type": "suggestion", + "commentData": [ + { + "commentText": "This button has insufficient color contrast.", + "from": { + "userId": "a11y-bot" + }, + "agent": { + "agentSource": "external", + "agentName": "Accessibility Bot", + "agentId": "a11y-bot", + "reason": { + "title": "Low color contrast", + "description": "Contrast ratio is 2.1:1, below the 4.5:1 WCAG AA threshold.", + "severity": "high", + "findingType": "pin" + } + } + } + ] + } + ] + } +} +``` + +#### Add a private (restricted) comment annotation + +Use `visibility` to limit who can see the annotation. + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "visibility": { + "type": "restricted", + "userIds": ["user_sarah_chen", "user_john_smith"] + }, + "commentData": [ + { + "commentText": "Internal note: don't ship this section yet.", + "from": { + "userId": "user_john_smith", + "name": "John Smith", + "email": "john.smith@acme-corp.com" + } + } + ] + } + ] + } +} +``` + # Response #### Success Response diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx index 844940725..02eb683af 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2.mdx @@ -65,9 +65,45 @@ Prior to using this API, you must: Array of User IDs. Limit: Only 30 IDs can be passed at a time. - {/* - Order of results based on `lastUpdated` timestamp. Options: `asc` or `desc`. Default: `desc`. - */} + + Array of User IDs. Filters annotations that mention (tag) any of these users. + + + + Filter annotations resolved by the given user ID. + + + + Filter to agent annotations created by the given agent ID. + + + + Filter to agent annotations from the given agent execution / run ID. + + + + Filter to agent annotations of the given agent type. Must be one of: `built-in`, `custom`, or `external`. + + + + Filter to agent annotations from the given source. Must be one of: `velt` or `external`. + + + + When true, returns only fresh (unaccepted) agent suggestions. + + + + When true, returns all agent annotations regardless of status. + + + + Only one agent filter (`agentId`, `executionId`, `agentType`, `agentSource`, `agentSuggestions`, or `agentComments`) may be supplied per request. + + + + Order of results based on `lastUpdated` timestamp. Must be one of: `asc` or `desc`. Default: `desc`. + Status IDs of the annotations to filter on. @@ -243,6 +279,19 @@ Prior to using this API, you must: ``` +#### 10. Get agent annotations by organizationId, documentId, and agentId + +```JSON +{ + "data": { + "organizationId": "yourOrganizationId", + "documentId": "yourDocumentId", + "agentId": "spell-check" + } +} +``` + +Agent annotations in the response carry `type: "suggestion"` and `sourceType: "agent"` at the annotation root, the annotation-root `agent` block, and the `agent` block on the agent-authored comment (`comments[].agent`). Both `agent` blocks are returned lean — only the internal `agentFields` filter tokens are omitted (see Response Field Notes below). # Response @@ -252,7 +301,12 @@ Prior to using this API, you must: - `reactionAnnotations`: Array of full reaction annotation objects attached to a comment. Each reaction includes the `icon`, `fromUsers` (the users who reacted), `location`, `locationId`, `commentAnnotationId`, `context`, `type`, `annotationId`, and `lastUpdated`. - `viewedBy`: This field is not currently returned by this endpoint. - `createdAt` and `lastUpdated`: Timestamps are returned in milliseconds since epoch for annotations and reactions, and in ISO 8601 format for comments. -- `context.access` / `context.accessFields`: Access control metadata for the annotation (e.g. `{ "default": "velt" }`). +- `type`: Annotation kind, either `comment` (a regular collaboration comment) or `suggestion` (an agent-produced finding). +- `sourceType`: How the annotation/comment was created. `rest-api` for annotations created via this REST API, or `agent` for agent-authored annotations and comments. +- `agent`: Returned at the annotation root (for agent-authored annotations) and on each agent-authored **comment** (`comments[].agent`). Contains `agentId`, `agentType` (`built-in` / `custom` / `external`), `agentSource` (`velt` / `external`), `executionId`, `agentName`, `url`, and the `reason` finding object (`title`, `description`, `severity`, `findingType`, etc.). The internal `agentFields` filter tokens are not returned on either block. +- `suggestion`: Lifecycle object present only when `type` is `suggestion`, e.g. `{ "status": "pending" }`. `status` is one of `pending`, `accepted`, or `rejected`. +- `visibilityConfig`: Visibility of the annotation, e.g. `{ "type": "public" }`. `type` is one of `public`, `organizationPrivate`, or `restricted`. +- `context.access` / `context.accessFields`: Access control metadata for the annotation (e.g. `{ "default": "velt" }`). When `visibility` is set on creation, the resolved access tokens appear in `context.accessFields`. - `hasDraftComments`: Boolean indicating whether the annotation has any draft comments. diff --git a/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx b/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx index 1ffe9b203..60e6c8ae8 100644 --- a/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comments/add-comments.mdx @@ -148,6 +148,71 @@ Use this API to add comments within a specific CommentAnnotation. + + Marks this comment as an agent-authored reply. V2 only. When set, the server stamps `sourceType: "agent"` on the comment. Discriminated on `agentSource`. + + + Origin of the agent. Must be one of: `velt` or `external`. + + + Agent ID. Required when `agentSource` is `velt` (a built-in agent like `spell-check`, or a custom agent ID that is verified server-side). Optional and opaque (never validated) when `agentSource` is `external`. + + + Execution / run ID for this agent invocation. + + + Display name for the agent. **Required when `agentSource` is `external`** (the only source of truth for an external agent's name). Not used for `velt` agents (their name is resolved server-side). + + + Page URL associated with the finding. + + + Finding details produced by the agent. Additional custom fields are preserved. + + + Short finding title. + + + Finding description. + + + Severity of the finding. Must be one of: `critical`, `high`, `medium`, `low`, or `info`. + + + Unique identifier for the finding. + + + Type of finding. Must be one of: `text`, `pin`, or `page`. + + + Custom issue classification. + + + Confidence score for the finding. Integer between 0 and 100. + + + Suggested change in plain text. + + + Suggested fix for the finding. + + + Relevant HTML snippet for the finding. + + + CSS/HTML selector pointing to the finding location. + + + Provenance of the rule that triggered the finding. Must be one of: `instructions` or `knowledge`. + + + Knowledge section that triggered the finding. + + + + + + @@ -156,6 +221,10 @@ Use this API to add comments within a specific CommentAnnotation. ## **Example Requests** + +This endpoint adds comments (including agent replies) to an existing CommentAnnotation. Annotation-level fields such as `type` (`comment` / `suggestion`) and `visibility` are set when the annotation is created or updated via the [Add Comment Annotations](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations) and Update Comment Annotations APIs — they are not accepted on this endpoint. + + #### 1. Add comment in a CommentAnnotation by organizationId, documentId, and annotationId ```JSON @@ -245,6 +314,40 @@ When `verifyUserPermissions` is enabled, the API verifies the user has access to } ``` +#### 4. Add an agent reply + +Attach an `agent` block to mark the comment as agent-authored. The server stamps `sourceType: "agent"` on the comment. + +```JSON +{ + "data": { + "organizationId": "yourOrganizationId", + "documentId": "yourDocumentId", + "annotationId": "yourAnnotationId", + "commentData": [ + { + "commentText": "I fixed the spelling. Please re-review.", + "from": { + "userId": "spell-check", + "name": "Spell Check Agent" + }, + "agent": { + "agentSource": "velt", + "agentId": "spell-check", + "executionId": "exec_124", + "reason": { + "title": "Spelling corrected", + "description": "Updated 'Welcom' to 'Welcome'.", + "severity": "info", + "findingType": "text" + } + } + } + ] + } +} +``` + # Response #### Success Response diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx new file mode 100644 index 000000000..30d0629e6 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/activityconfig-get.mdx @@ -0,0 +1,89 @@ +--- +title: "Get Activity Config" +api: "POST https://api.velt.dev/v2/workspace/activityconfig/get" +--- + +Use this API to retrieve the current activity logs configuration for a workspace. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/activityconfig/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +This endpoint does not require a request body. + +# Example Request + +```JSON +{ + "data": {} +} +``` + +# Example Response + + +If a workspace has never configured activity logs, `activityServiceConfig` defaults to `{ "isEnabled": false }` (default-disabled). + + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Activity logs configuration retrieved successfully.", + "data": { + "activityServiceConfig": { + "isEnabled": false, + "immutable": false, + "triggers": { "comment": { "added" : true } } + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Invalid API key." + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Activity logs configuration retrieved successfully.", + "data": { + "activityServiceConfig": { + "isEnabled": false, + "immutable": false, + "triggers": { "comment": { "added" : true } } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx new file mode 100644 index 000000000..0c2a21623 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/activityconfig-update.mdx @@ -0,0 +1,122 @@ +--- +title: "Update Activity Config" +api: "POST https://api.velt.dev/v2/workspace/activityconfig/update" +--- + +Use this API to update the activity logs configuration for a workspace. The `activityServiceConfig` object must contain at least one sub-field. The config is deep-merged with the existing value, so omitted sub-fields are preserved (including `enabledTime` when you omit it). + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +**Defaults on first enable.** If you enable activity logs (`activityServiceConfig.isEnabled: true`) and no `activityServiceConfig` exists yet, defaults are seeded automatically: the standard `comment` triggers are turned on (including the `comment_annotation.suggestion_accept` / `comment_annotation.suggestion_reject` triggers, which are active by default for activity logs), `immutable` is set to `true`, and `enabledTime` is stamped with the current timestamp when you don't provide one. Any values you send in the same request (including `immutable: false` or your own `enabledTime`) are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ activityServiceConfig }` — the same shape returned by [Get Activity Config](/api-reference/rest-apis/v2/workspace/activityconfig-get), including any seeded defaults. `isEnabled` is always present (defaults to `false` when neither your request nor the stored config sets it). + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/activityconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Activity service configuration object. Must contain at least one sub-field. + + + Whether activity logging is enabled. + + + Timestamp (ms) when activity logging was enabled. Preserved when omitted. + + + Whether activity logs are immutable. + + + Event triggers that produce activity logs. Supports the `comment` trigger group — a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. The `comment_annotation.suggestion_accept` / `comment_annotation.suggestion_reject` triggers are active by default for activity logs — set them to `false` to stop logging suggestion accept/reject events. + + + + + + +# Example Request + +```JSON +{ + "data": { + "activityServiceConfig": { + "isEnabled": true, + "immutable": false + } + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Activity logs configuration updated successfully.", + "data": { + "activityServiceConfig": { + "isEnabled": true, + "immutable": false, + "enabledTime": 1717520000000 + } + } + } +} +``` + +#### Failure Response + +##### If activityServiceConfig has no sub-fields + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "At least one field must be provided for update" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Activity logs configuration updated successfully.", + "data": { + "activityServiceConfig": { + "isEnabled": true, + "immutable": false, + "enabledTime": 1717520000000 + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikey-create.mdx b/api-reference/rest-apis/v2/workspace/apikey-create.mdx index 5268d4a0f..0144c81fd 100644 --- a/api-reference/rest-apis/v2/workspace/apikey-create.mdx +++ b/api-reference/rest-apis/v2/workspace/apikey-create.mdx @@ -6,9 +6,13 @@ api: "POST https://api.velt.dev/v2/workspace/apikey/create" Use this API to create a new API key for a workspace. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. + +This API currently supports creating **`testing`** API keys only. + + # Endpoint `POST https://api.velt.dev/v2/workspace/apikey/create` @@ -19,8 +23,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body @@ -33,7 +37,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Email address of the API key owner. - API key type. Accepted values: `"testing"` or `"production"`. + API key type. Currently only `"testing"` is supported. Whether to create an auth token along with the API key. Recommended: `true`. diff --git a/api-reference/rest-apis/v2/workspace/apikey-update.mdx b/api-reference/rest-apis/v2/workspace/apikey-update.mdx index 0c57de38e..84c1b0da8 100644 --- a/api-reference/rest-apis/v2/workspace/apikey-update.mdx +++ b/api-reference/rest-apis/v2/workspace/apikey-update.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/apikey/update" Use this API to update the name of an existing API key. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx new file mode 100644 index 000000000..ab365a366 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx @@ -0,0 +1,109 @@ +--- +title: "Get API Key Config" +api: "POST https://api.velt.dev/v2/workspace/apikeyconfig/get" +--- + +Use this API to retrieve the app configuration for a workspace API key: owner email, plan info, default document access type, the private-comments flag, the JWT / auto-org-user toggles, and the configured AI model keys (masked). + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/get` is still supported and routes to this same endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/apikeyconfig/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +This endpoint does not require a request body. + +# Example Request + +```JSON +{ + "data": {} +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "API key metadata retrieved successfully.", + "data": { + "ownerEmail": "owner@example.com", + "planInfo": { + "type": "sdk test" + }, + "defaultDocumentAccessType": "public", + "isPrivateCommentsEnabled": false, + "requireJwtToken": false, + "requireAutoOrgUser": false, + "aiModelsConfig": { + "openai": { + "displayText": "sk-...XyZ" + } + } + } + } +} +``` + + +`aiModelsConfig` is a map of `provider -> { displayText }` and is **masked** — the raw or encrypted AI model key is never returned. It is absent when no AI keys are configured. `defaultDocumentAccessType` is one of `public`, `restricted`, or `organizationPrivate` (defaults to `public`). + + +#### Failure Response + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Invalid API key." + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "API key metadata retrieved successfully.", + "data": { + "ownerEmail": "owner@example.com", + "planInfo": { + "type": "sdk test" + }, + "defaultDocumentAccessType": "public", + "isPrivateCommentsEnabled": false, + "requireJwtToken": false, + "requireAutoOrgUser": false, + "aiModelsConfig": { + "openai": { + "displayText": "sk-...XyZ" + } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx new file mode 100644 index 000000000..509fc6e46 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx @@ -0,0 +1,136 @@ +--- +title: "Update API Key Config" +api: "POST https://api.velt.dev/v2/workspace/apikeyconfig/update" +--- + +Use this API to update the app configuration for a workspace API key. Every field is optional, but **at least one** must be provided. Unknown fields are rejected. All writes are field-merge only — no fields are removed. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/update` is still supported and routes to this same endpoint. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/apikeyconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + At least one of the following fields must be provided. + + + Enable (`true`) or disable (`false`) private comments for this API key. + + + When `true`, the SDK requires a signed JWT to authenticate. + + + When `true`, users are auto-added to the organization on first access. + + + Workspace-default document access type. One of `public`, `restricted`, or `organizationPrivate`. + + + Array of AI model provider keys — pass multiple entries to update several providers in one call. Each raw key is encrypted at rest and is never returned in any response. Must contain at least one entry. + + + AI provider. One of `openai`, `anthropic`, or `gemini`. + + + The provider API key to store (encrypted). + + + + + + +# Example Request + +```JSON +{ + "data": { + "requireJwtToken": true, + "defaultDocumentAccessType": "restricted", + "aiModelApiKey": [ + { "provider": "openai", "customerApiKey": "sk-openai-..." }, + { "provider": "anthropic", "customerApiKey": "sk-ant-..." }, + { "provider": "gemini", "customerApiKey": "AIza..." } + ] + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "API key configuration updated successfully.", + "data": { + "requireJwtToken": true, + "defaultDocumentAccessType": "restricted", + "aiModelsConfig": { + "openai": { "displayText": "sk-open...xxxxxxxxxxxxxxxxxxxxxxx" }, + "anthropic": { "displayText": "sk-ant-...xxxxxxxxxxxxxxxxxxxxx" }, + "gemini": { "displayText": "AIza...xxxxxxxxxxxxxxxxxxxxxxxxx" } + } + } + } +} +``` + + +The response echoes the post-write values for the fields you provided. For `aiModelApiKey`, the keys come back masked under `aiModelsConfig` as a map of `provider -> { displayText }` (the same shape as [Get API Key Config](/api-reference/rest-apis/v2/workspace/apikeyconfig-get)) — the raw key value is never returned. When `enablePrivateComments` is the only field and its value already matches the current value, the write is skipped internally and the response is simply `{ "enablePrivateComments": }`. + + +#### Failure Response + +##### If no field is provided, or an unknown field is sent + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "At least one field must be provided for update" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "API key configuration updated successfully.", + "data": { + "requireJwtToken": true, + "defaultDocumentAccessType": "restricted", + "aiModelsConfig": { + "openai": { "displayText": "sk-open...xxxxxxxxxxxxxxxxxxxxxxx" }, + "anthropic": { "displayText": "sk-ant-...xxxxxxxxxxxxxxxxxxxxx" }, + "gemini": { "displayText": "AIza...xxxxxxxxxxxxxxxxxxxxxxxxx" } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikeys-get.mdx b/api-reference/rest-apis/v2/workspace/apikeys-get.mdx index 29ed3bdd0..84c69044a 100644 --- a/api-reference/rest-apis/v2/workspace/apikeys-get.mdx +++ b/api-reference/rest-apis/v2/workspace/apikeys-get.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/apikeys/get" Use this API to retrieve a list of API keys for a workspace. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx b/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx index 221c6e739..6f3645e5f 100644 --- a/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx +++ b/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/authtoken/reset" Use this API to reset the auth token for a specific API key. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/authtokens-get.mdx b/api-reference/rest-apis/v2/workspace/authtokens-get.mdx index 81a207476..968a8c715 100644 --- a/api-reference/rest-apis/v2/workspace/authtokens-get.mdx +++ b/api-reference/rest-apis/v2/workspace/authtokens-get.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/authtokens/get" Use this API to retrieve all auth tokens associated with a specific API key. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your Workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx b/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx index 75ade3105..329a51b7b 100644 --- a/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/emailconfig-update.mdx @@ -9,6 +9,14 @@ Use this API to update the email service configuration for a workspace. At least This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +**Defaults on first enable.** If you enable the service — either with `useEmailService: true` or by sending `emailServiceConfig.type: "custom"` — and the stored config has no `triggers` yet (defaults are seeded even if `type` / SendGrid fields already exist), defaults are seeded automatically: the service is marked as a custom provider (`type: "custom"`), the standard `comment` triggers and all `huddle` triggers are turned on, and `useEmailService` is set to `true`. Existing non-trigger fields are preserved, and any `emailServiceConfig` values you send in the same request are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ useEmailService, emailServiceConfig }` — the same shape returned by [Get Email Config](/api-reference/rest-apis/v2/workspace/emailconfig-get). Fields not part of your request fall back to the existing stored values. + + # Endpoint `POST https://api.velt.dev/v2/workspace/emailconfig/update` @@ -97,7 +105,15 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut "result": { "status": "success", "message": "Email configuration updated successfully.", - "data": null + "data": { + "useEmailService": true, + "emailServiceConfig": { + "type": "sendgrid", + "apiKey": "SG.xxxxxxxxxx", + "fromEmail": "noreply@example.com", + "fromCompany": "Example Corp" + } + } } } ``` @@ -119,7 +135,15 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut "result": { "status": "success", "message": "Email configuration updated successfully.", - "data": null + "data": { + "useEmailService": true, + "emailServiceConfig": { + "type": "sendgrid", + "apiKey": "SG.xxxxxxxxxx", + "fromEmail": "noreply@example.com", + "fromCompany": "Example Corp" + } + } } } ``` diff --git a/api-reference/rest-apis/v2/workspace/get.mdx b/api-reference/rest-apis/v2/workspace/get.mdx index 4d88d63ae..59af274ad 100644 --- a/api-reference/rest-apis/v2/workspace/get.mdx +++ b/api-reference/rest-apis/v2/workspace/get.mdx @@ -6,7 +6,7 @@ api: "POST https://api.velt.dev/v2/workspace/get" Use this API to retrieve details of an existing Velt workspace. -This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-auth-token` (from the Create Workspace response) as headers. +This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-velt-workspace-auth-token` (from the Create Workspace response) as headers. # Endpoint @@ -19,8 +19,8 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v Your workspace ID. - - Your [Auth Token](/security/auth-tokens). + + Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. # Body diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx new file mode 100644 index 000000000..762cb568c --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-get.mdx @@ -0,0 +1,103 @@ +--- +title: "Get Notification Config" +api: "POST https://api.velt.dev/v2/workspace/notificationconfig/get" +--- + +Use this API to retrieve the current in-app notification service configuration for a workspace. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +The numeric `delayConfig` / `batchConfig` fields returned here are constrained to these ranges when set via [Update Notification Config](/api-reference/rest-apis/v2/workspace/notificationconfig-update): `delaySeconds` `10`–`15552000` (6 months), `batchWindowSeconds` `10`–`604800` (1 week), `maxActivities` `2`–`50`. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/notificationconfig/get` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +This endpoint does not require a request body. + +# Example Request + +```JSON +{ + "data": {} +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Notification configuration retrieved successfully.", + "data": { + "useNotificationService": false, + "notificationServiceConfig": { + "triggers": { "comment": { }, "huddle": { } }, + "delayConfig": { + "isEnabled": false, + "delaySeconds": 10 + }, + "batchConfig": { + "document": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 }, + "user": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 } + } + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "status": "PERMISSION_DENIED", + "message": "Invalid API key." + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Notification configuration retrieved successfully.", + "data": { + "useNotificationService": false, + "notificationServiceConfig": { + "triggers": { "comment": { }, "huddle": { } }, + "delayConfig": { + "isEnabled": false, + "delaySeconds": 10 + }, + "batchConfig": { + "document": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 }, + "user": { "isEnabled": false, "batchWindowSeconds": 10, "maxActivities": 2 } + } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx new file mode 100644 index 000000000..b4f345e5e --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/notificationconfig-update.mdx @@ -0,0 +1,172 @@ +--- +title: "Update Notification Config" +api: "POST https://api.velt.dev/v2/workspace/notificationconfig/update" +--- + +Use this API to update the in-app notification service configuration for a workspace. At least one of `useNotificationService` or `notificationServiceConfig` must be provided. The config is deep-merged with the existing value, so omitted sub-fields are preserved. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +The numeric delay/batching fields must be integers within these ranges, otherwise the request is rejected with `INVALID_ARGUMENT`: +- `delayConfig.delaySeconds`: `10`–`15552000` (10 seconds to 6 months) +- `batchConfig.document.batchWindowSeconds` / `batchConfig.user.batchWindowSeconds`: `10`–`604800` (10 seconds to 1 week) +- `batchConfig.document.maxActivities` / `batchConfig.user.maxActivities`: `2`–`50` + + + +**Defaults on first enable.** If you enable the service (`useNotificationService: true`) and the stored config has no `triggers` yet (defaults are seeded even if `delayConfig` / `batchConfig` already exist), a default set of triggers is seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on. Delay and batching stay off — no `delayConfig` or `batchConfig` is written by the seeding. Existing non-trigger fields are preserved, and any `notificationServiceConfig` values you send in the same request are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ useNotificationService, notificationServiceConfig }` — the same shape returned by [Get Notification Config](/api-reference/rest-apis/v2/workspace/notificationconfig-get). Fields not part of your request fall back to the existing stored values. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/notificationconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Whether to enable the in-app notification service. + + + Notification service configuration object. + + + Event triggers that activate in-app notifications. Supports `comment` and `huddle` trigger groups. Each is a map of event-type string to a boolean to enable (`true`) or disable (`false`) that trigger. See [Webhooks](/webhooks/advanced) for the full list of event types. + + + Notification delay settings. + + + Whether delayed notifications are enabled. + + + Delay before sending a notification, in seconds. Must be an integer between `10` and `15552000` (10 seconds to 6 months). + + + + + Notification batching settings, with independent `document` and `user` configs. + + + Per-document batching. + + + Whether document-level batching is enabled. + + + Time window to group document-level notifications, in seconds. Must be an integer between `10` and `604800` (10 seconds to 1 week). + + + Flush the batch once this many activities accumulate. Must be an integer between `2` and `50`. + + + + + Per-user batching. + + + Whether user-level batching is enabled. + + + Time window to group user-level notifications, in seconds. Must be an integer between `10` and `604800` (10 seconds to 1 week). + + + Flush the batch once this many activities accumulate. Must be an integer between `2` and `50`. + + + + + + + + + + +# Example Request + +```JSON +{ + "data": { + "useNotificationService": true, + "notificationServiceConfig": { + "delayConfig": { + "isEnabled": true, + "delaySeconds": 30 + } + } + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Notification configuration updated successfully.", + "data": { + "useNotificationService": true, + "notificationServiceConfig": { + "delayConfig": { + "isEnabled": true, + "delaySeconds": 30 + } + } + } + } +} +``` + +#### Failure Response + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "At least one of useNotificationService or notificationServiceConfig must be provided" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Notification configuration updated successfully.", + "data": { + "useNotificationService": true, + "notificationServiceConfig": { + "delayConfig": { + "isEnabled": true, + "delaySeconds": 30 + } + } + } + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/apikeymetadata-get.mdx b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx similarity index 57% rename from api-reference/rest-apis/v2/workspace/apikeymetadata-get.mdx rename to api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx index 1cbc6d08a..41ee0f636 100644 --- a/api-reference/rest-apis/v2/workspace/apikeymetadata-get.mdx +++ b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-get.mdx @@ -1,9 +1,9 @@ --- -title: "Get API Key Metadata" -api: "POST https://api.velt.dev/v2/workspace/apikeymetadata/get" +title: "Get Permission Provider Config" +api: "POST https://api.velt.dev/v2/workspace/permissionproviderconfig/get" --- -Use this API to retrieve metadata associated with a workspace API key. +Use this API to retrieve the current permission provider configuration for a workspace. This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. @@ -11,7 +11,7 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut # Endpoint -`POST https://api.velt.dev/v2/workspace/apikeymetadata/get` +`POST https://api.velt.dev/v2/workspace/permissionproviderconfig/get` # Headers @@ -43,13 +43,13 @@ This endpoint does not require a request body. { "result": { "status": "success", - "message": "API key metadata retrieved successfully.", + "message": "Permission provider configuration retrieved successfully.", "data": { - "defaultDocumentAccessType": "public", - "planInfo": { - "type": "sdk test" - }, - "ownerEmail": "owner@example.com" + "usePermissionProvider": false, + "permissionProviderConfig": { + "permissionProviderUrl": "", + "authToken": "" + } } } } @@ -71,13 +71,13 @@ This endpoint does not require a request body. { "result": { "status": "success", - "message": "API key metadata retrieved successfully.", + "message": "Permission provider configuration retrieved successfully.", "data": { - "defaultDocumentAccessType": "public", - "planInfo": { - "type": "sdk test" - }, - "ownerEmail": "owner@example.com" + "usePermissionProvider": false, + "permissionProviderConfig": { + "permissionProviderUrl": "", + "authToken": "" + } } } } diff --git a/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx new file mode 100644 index 000000000..3e9da9e70 --- /dev/null +++ b/api-reference/rest-apis/v2/workspace/permissionproviderconfig-update.mdx @@ -0,0 +1,102 @@ +--- +title: "Update Permission Provider Config" +api: "POST https://api.velt.dev/v2/workspace/permissionproviderconfig/update" +--- + +Use this API to update the permission provider configuration for a workspace. At least one of `usePermissionProvider` or `permissionProviderConfig` must be provided. The config is merged with the existing value, so e.g. the `authToken` is preserved when only the URL changes. + + +This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + + + +**Defaults on first enable.** If you enable the provider (`usePermissionProvider: true`) and no `permissionProviderConfig` exists yet, an empty config is seeded (`permissionProviderUrl` and `authToken` set to empty strings) and returned in the response `data`. Any `permissionProviderConfig` values you send in the same request are merged on top. + + +# Endpoint + +`POST https://api.velt.dev/v2/workspace/permissionproviderconfig/update` + +# Headers + + + Your API key. + + + + Your [Auth Token](/security/auth-tokens). + + +# Body + +#### Params + + + + + Whether to enable the permission provider. + + + Permission provider configuration object. + + + Provider URL. Must be an empty string (to clear the value) or a valid `http`/`https` URL. Any other value is rejected. + + + Auth token sent to the permission provider. + + + + + + +# Example Request + +```JSON +{ + "data": { + "usePermissionProvider": true, + "permissionProviderConfig": { + "permissionProviderUrl": "https://example.com/permissions", + "authToken": "provider_auth_token_here" + } + } +} +``` + +# Example Response + +#### Success Response + +```JSON +{ + "result": { + "status": "success", + "message": "Permission provider configuration updated successfully." + } +} +``` + +#### Failure Response + +##### If permissionProviderUrl is not empty and not a valid http(s) URL + +```JSON +{ + "error": { + "status": "INVALID_ARGUMENT", + "message": "Please enter a valid URL" + } +} +``` + + +```js +{ + "result": { + "status": "success", + "message": "Permission provider configuration updated successfully." + } +} +``` + diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx index 0318b63d7..34f201bc9 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-get.mdx @@ -9,6 +9,10 @@ Use this API to retrieve the current webhook service configuration for a workspa This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +Currently only supported for Basic Webhooks. + + # Endpoint `POST https://api.velt.dev/v2/workspace/webhookconfig/get` diff --git a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx index e4166d54b..e14349c86 100644 --- a/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/webhookconfig-update.mdx @@ -9,6 +9,18 @@ Use this API to update the webhook service configuration for a workspace. At lea This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. + +Currently only supported for Basic Webhooks. + + + +**Defaults on first enable.** If you enable the service (`useWebhookService: true`) and the stored config has no `triggers` yet (defaults are seeded even if `authToken` / URLs already exist), defaults are seeded automatically: the standard `comment` triggers and all `huddle` triggers are turned on, the `crdt` and `recorder` triggers are off, and `enableDataProtection` is `false`. The opt-in `suggestion_accept` / `suggestion_reject` comment triggers stay off until you enable them explicitly. Existing non-trigger fields are preserved, and any `webhookServiceConfig` values you send in the same request are merged on top of these defaults. + + + +The response `data` echoes the latest post-write state as `{ useWebhookService, webhookServiceConfig }` — the same shape returned by [Get Webhook Config](/api-reference/rest-apis/v2/workspace/webhookconfig-get). Fields not part of your request fall back to the existing stored values. + + # Endpoint `POST https://api.velt.dev/v2/workspace/webhookconfig/update` @@ -77,6 +89,12 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut Trigger when a thread's priority changes. + + Trigger when a suggestion is accepted. Opt-in: disabled by default, enable it explicitly to receive this event. + + + Trigger when a suggestion is rejected. Opt-in: disabled by default, enable it explicitly to receive this event. + Trigger when a reaction is added to a comment. @@ -114,7 +132,14 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut "result": { "status": "success", "message": "Webhook configuration updated successfully.", - "data": null + "data": { + "useWebhookService": true, + "webhookServiceConfig": { + "authToken": "webhook_auth_token_here", + "rawNotificationUrl": "https://example.com/webhooks/raw", + "processedNotificationUrl": "https://example.com/webhooks/processed" + } + } } } ``` @@ -136,7 +161,14 @@ This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-aut "result": { "status": "success", "message": "Webhook configuration updated successfully.", - "data": null + "data": { + "useWebhookService": true, + "webhookServiceConfig": { + "authToken": "webhook_auth_token_here", + "rawNotificationUrl": "https://example.com/webhooks/raw", + "processedNotificationUrl": "https://example.com/webhooks/processed" + } + } } } ``` From dc39217b442e9194ecb288021c53a7aa7abd730d Mon Sep 17 00:00:00 2001 From: Rakesh Date: Fri, 5 Jun 2026 19:43:25 -0700 Subject: [PATCH 2/4] docs(rest-apis): add workspace config endpoints to navigation Port the workspace-related docs.json navigation changes from raghul/agent-docs (PR #168) that accompany the ported v2/workspace pages: - Remove the deleted apikeymetadata-get entry (renamed to permissionproviderconfig-get) - Add API Key Configuration, Activity Configuration, Notification Configuration, and Permission Provider Configuration groups Unrelated navigation changes (suggestions, AI Agents, REST Agents) are intentionally excluded since those pages are not part of this branch. Co-authored-by: Cursor --- docs.json | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 4de505e7d..1bb167aad 100644 --- a/docs.json +++ b/docs.json @@ -820,8 +820,14 @@ "pages": [ "api-reference/rest-apis/v2/workspace/apikey-create", "api-reference/rest-apis/v2/workspace/apikeys-get", - "api-reference/rest-apis/v2/workspace/apikey-update", - "api-reference/rest-apis/v2/workspace/apikeymetadata-get" + "api-reference/rest-apis/v2/workspace/apikey-update" + ] + }, + { + "group": "API Key Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/apikeyconfig-get", + "api-reference/rest-apis/v2/workspace/apikeyconfig-update" ] }, { @@ -852,6 +858,27 @@ "api-reference/rest-apis/v2/workspace/webhookconfig-get", "api-reference/rest-apis/v2/workspace/webhookconfig-update" ] + }, + { + "group": "Activity Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/activityconfig-get", + "api-reference/rest-apis/v2/workspace/activityconfig-update" + ] + }, + { + "group": "Notification Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/notificationconfig-get", + "api-reference/rest-apis/v2/workspace/notificationconfig-update" + ] + }, + { + "group": "Permission Provider Configuration", + "pages": [ + "api-reference/rest-apis/v2/workspace/permissionproviderconfig-get", + "api-reference/rest-apis/v2/workspace/permissionproviderconfig-update" + ] } ] } From 8246bf9aaeaa0ebfe13a5aa66c497652e0864115 Mon Sep 17 00:00:00 2001 From: Rakesh Date: Fri, 5 Jun 2026 19:45:44 -0700 Subject: [PATCH 3/4] docs(rest-apis): remove legacy apikeymetadata path notes from apikeyconfig pages Co-authored-by: Cursor --- api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx | 4 ---- api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx | 4 ---- 2 files changed, 8 deletions(-) diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx index ab365a366..8cb4b58f8 100644 --- a/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-get.mdx @@ -9,10 +9,6 @@ Use this API to retrieve the app configuration for a workspace API key: owner em This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. - -The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/get` is still supported and routes to this same endpoint. - - # Endpoint `POST https://api.velt.dev/v2/workspace/apikeyconfig/get` diff --git a/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx index 509fc6e46..bb8d9e331 100644 --- a/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx +++ b/api-reference/rest-apis/v2/workspace/apikeyconfig-update.mdx @@ -9,10 +9,6 @@ Use this API to update the app configuration for a workspace API key. Every fiel This endpoint uses **API-key-level auth**: pass `x-velt-api-key` and `x-velt-auth-token` as headers. You can obtain these from the [Get Auth Tokens](/api-reference/rest-apis/v2/workspace/authtokens-get) endpoint. - -The legacy path `POST https://api.velt.dev/v2/workspace/apikeymetadata/update` is still supported and routes to this same endpoint. - - # Endpoint `POST https://api.velt.dev/v2/workspace/apikeyconfig/update` From 4ac959600791790afef5c1bfdbf323bb093a80c0 Mon Sep 17 00:00:00 2001 From: Rakesh Date: Fri, 5 Jun 2026 19:47:15 -0700 Subject: [PATCH 4/4] docs(rest-apis): remove legacy x-velt-auth-token header fallback notes Co-authored-by: Cursor --- api-reference/rest-apis/v2/workspace/apikey-create.mdx | 2 +- api-reference/rest-apis/v2/workspace/apikey-update.mdx | 2 +- api-reference/rest-apis/v2/workspace/apikeys-get.mdx | 2 +- api-reference/rest-apis/v2/workspace/authtoken-reset.mdx | 2 +- api-reference/rest-apis/v2/workspace/authtokens-get.mdx | 2 +- api-reference/rest-apis/v2/workspace/get.mdx | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/api-reference/rest-apis/v2/workspace/apikey-create.mdx b/api-reference/rest-apis/v2/workspace/apikey-create.mdx index 0144c81fd..926108101 100644 --- a/api-reference/rest-apis/v2/workspace/apikey-create.mdx +++ b/api-reference/rest-apis/v2/workspace/apikey-create.mdx @@ -24,7 +24,7 @@ This API currently supports creating **`testing`** API keys only. - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + Your workspace [Auth Token](/security/auth-tokens). # Body diff --git a/api-reference/rest-apis/v2/workspace/apikey-update.mdx b/api-reference/rest-apis/v2/workspace/apikey-update.mdx index 84c1b0da8..bb80d56a5 100644 --- a/api-reference/rest-apis/v2/workspace/apikey-update.mdx +++ b/api-reference/rest-apis/v2/workspace/apikey-update.mdx @@ -20,7 +20,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + Your workspace [Auth Token](/security/auth-tokens). # Body diff --git a/api-reference/rest-apis/v2/workspace/apikeys-get.mdx b/api-reference/rest-apis/v2/workspace/apikeys-get.mdx index 84c69044a..91b7c77f4 100644 --- a/api-reference/rest-apis/v2/workspace/apikeys-get.mdx +++ b/api-reference/rest-apis/v2/workspace/apikeys-get.mdx @@ -20,7 +20,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + Your workspace [Auth Token](/security/auth-tokens). # Body diff --git a/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx b/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx index 6f3645e5f..545d81e28 100644 --- a/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx +++ b/api-reference/rest-apis/v2/workspace/authtoken-reset.mdx @@ -20,7 +20,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + Your workspace [Auth Token](/security/auth-tokens). # Body diff --git a/api-reference/rest-apis/v2/workspace/authtokens-get.mdx b/api-reference/rest-apis/v2/workspace/authtokens-get.mdx index 968a8c715..294425890 100644 --- a/api-reference/rest-apis/v2/workspace/authtokens-get.mdx +++ b/api-reference/rest-apis/v2/workspace/authtokens-get.mdx @@ -20,7 +20,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + Your workspace [Auth Token](/security/auth-tokens). # Body diff --git a/api-reference/rest-apis/v2/workspace/get.mdx b/api-reference/rest-apis/v2/workspace/get.mdx index 59af274ad..5e17dd319 100644 --- a/api-reference/rest-apis/v2/workspace/get.mdx +++ b/api-reference/rest-apis/v2/workspace/get.mdx @@ -20,7 +20,7 @@ This endpoint uses **workspace-level auth**: pass `x-velt-workspace-id` and `x-v - Your workspace [Auth Token](/security/auth-tokens). The legacy `x-velt-auth-token` header is still accepted as a fallback. + Your workspace [Auth Token](/security/auth-tokens). # Body