From 16d5d3c9cfb2296b6e8abfbc31301116f84c0691 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 18:36:06 +0000 Subject: [PATCH 1/2] docs: document suggestion payload on V2 comment annotations --- .../add-comment-annotations.mdx | 62 +++++++++++++++++++ .../update-comment-annotations.mdx | 26 ++++++++ 2 files changed, 88 insertions(+) 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 6acac9bdd..37da3cbf7 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 @@ -301,6 +301,32 @@ 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. + + Proposed-change payload for `type: "suggestion"` annotations. Persisted verbatim so reviewers (and your app's accept handler) can round-trip the target and the old/new values. Ignored when `type` is not `suggestion`. + + The schema is open — any additional custom fields you include are stored as-is alongside the fields below. `status` is server-owned: any caller-supplied value is dropped and the server stamps `pending` at create time (and `accepted` / `rejected` on the corresponding lifecycle action). + + + Stable ID of the thing being changed (for example, the record or field ID the suggestion applies to). Your accept handler uses this to locate what to update. + + + Kind of target the suggestion applies to (for example, `custom`, `text`, or a value your app defines). + + + The value at the time the suggestion was created. Can be any JSON-serializable value. + + + The proposed new value. Can be any JSON-serializable value. Your app writes this into its own state or backend when the suggestion is accepted. + + + Optional human-readable summary of the change (for example, `"row.123: 205 → 305"`). + + + Set to `true` when the live target value at accept time differs from `oldValue`. Informational — it does not block the accept. + + + + Caller-driven comment classification. Must be one of: `manual` or `chart`. Defaults to `manual` when omitted. @@ -573,6 +599,42 @@ To attach a finding from an agent run through your own framework, use `agentSour } ``` +#### Add a suggestion with a proposed-change payload + +Set `type: "suggestion"` and attach a `suggestion` object describing what should change. The server persists the payload verbatim and stamps `suggestion.status: "pending"`; any caller-supplied `status` is dropped. Additional custom fields inside `suggestion` are stored as-is. + +```JSON +{ + "data": { + "organizationId": "acme-corp", + "documentId": "design-mockup-v2", + "commentAnnotations": [ + { + "type": "suggestion", + "suggestion": { + "targetId": "row.123", + "targetType": "custom", + "oldValue": { "x": 205 }, + "newValue": { "x": 305 }, + "summary": "row.123: 205 → 305", + "driftDetected": false, + "myCustomField": "kept as-is" + }, + "commentData": [ + { + "commentText": "Bump x from 205 to 305 to match the spec.", + "from": { + "userId": "user_sarah_chen", + "name": "Sarah Chen" + } + } + ] + } + ] + } +} +``` + #### Add a private (restricted) comment annotation Use `visibility` to limit who can see the annotation. diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx index d727f4295..e6f1d8584 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx @@ -146,6 +146,32 @@ Additional filters can be applied using location IDs, annotation IDs, or user ID + + + Proposed-change payload for `type: "suggestion"` annotations. Any fields you send replace the persisted `suggestion` object. Only applied when the target annotation is a suggestion. + + The schema is open — additional custom fields are stored as-is. `suggestion.status` is server-owned and cannot be changed here: it is flipped to `accepted` or `rejected` only through the corresponding lifecycle actions (for example, accepting an agent suggestion). Any caller-supplied `status` is ignored. + + + Stable ID of the thing being changed. + + + Kind of target the suggestion applies to. + + + The value at the time the suggestion was created. + + + The proposed new value. + + + Optional human-readable summary of the change. + + + Set to `true` when the live target value differs from `oldValue`. + + + From b7873a87479fb17048af7effc5dc43013518554a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 18:37:23 +0000 Subject: [PATCH 2/2] docs: add SEO descriptions to V2 comment annotations add/update pages --- .../comment-annotations/add-comment-annotations.mdx | 1 + .../comment-annotations/update-comment-annotations.mdx | 1 + 2 files changed, 2 insertions(+) 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 37da3cbf7..ddf03decc 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 @@ -1,5 +1,6 @@ --- title: "Add Comment Annotations" +description: "Create V2 comment annotations via REST — plain comments, agent findings, suggestions with a proposed-change payload, and private annotations." api: "POST https://api.velt.dev/v2/commentannotations/add" --- diff --git a/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx b/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx index e6f1d8584..6379bda62 100644 --- a/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx +++ b/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations.mdx @@ -1,5 +1,6 @@ --- title: "Update Comment Annotations" +description: "Update V2 comment annotations via REST — patch status, priority, assignee, context, or suggestion payload by annotation, location, or user ID." api: "POST https://api.velt.dev/v2/commentannotations/update" ---