From f62b4f35dfe8e561f98301f511983f7cd25c90f6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 13 May 2026 11:31:30 +0000
Subject: [PATCH] Document inline comment anchor fields on /comments.create

Adds anchorText, anchorPrefix, and anchorSuffix request parameters to
the comments.create endpoint, enabling creation of inline comments
attached to a specific text range in a document.
---
 spec3.json | 14 +++++++++++++-
 spec3.yml  | 22 +++++++++++++++++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/spec3.json b/spec3.json
index 6a26736..ec33c5f 100644
--- a/spec3.json
+++ b/spec3.json
@@ -1750,7 +1750,7 @@
           "Comments"
         ],
         "summary": "Create a comment",
-        "description": "Add a comment or reply to a document, either `data` or `text` is required.",
+        "description": "Add a comment or reply to a document, either `data` or `text` is required. Provide `anchorText` to create an inline comment attached to a specific text range in the document.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -1777,6 +1777,18 @@
                     "type": "string",
                     "description": "The body of the comment in markdown.",
                     "example": "Sounds great"
+                  },
+                  "anchorText": {
+                    "type": "string",
+                    "description": "Plain text substring to anchor the comment to as an inline comment. The first occurrence in the document's plain text is used unless disambiguated by `anchorPrefix` and/or `anchorSuffix`."
+                  },
+                  "anchorPrefix": {
+                    "type": "string",
+                    "description": "Text immediately preceding `anchorText`, used to disambiguate between multiple occurrences. Requires `anchorText`."
+                  },
+                  "anchorSuffix": {
+                    "type": "string",
+                    "description": "Text immediately following `anchorText`, used to disambiguate between multiple occurrences. Requires `anchorText`."
                   }
                 },
                 "required": [
diff --git a/spec3.yml b/spec3.yml
index 0ea6806..3f36cac 100644
--- a/spec3.yml
+++ b/spec3.yml
@@ -1366,7 +1366,10 @@ paths:
       tags:
         - Comments
       summary: Create a comment
-      description: Add a comment or reply to a document, either `data` or `text` is required.
+      description:
+        Add a comment or reply to a document, either `data` or `text` is required.
+        Provide `anchorText` to create an inline comment attached to a specific
+        text range in the document.
       requestBody:
         content:
           application/json:
@@ -1389,6 +1392,23 @@ paths:
                   type: string
                   description: The body of the comment in markdown.
                   example: Sounds great
+                anchorText:
+                  type: string
+                  description:
+                    Plain text substring to anchor the comment to as an inline
+                    comment. The first occurrence in the document's plain text
+                    is used unless disambiguated by `anchorPrefix` and/or
+                    `anchorSuffix`.
+                anchorPrefix:
+                  type: string
+                  description:
+                    Text immediately preceding `anchorText`, used to disambiguate
+                    between multiple occurrences. Requires `anchorText`.
+                anchorSuffix:
+                  type: string
+                  description:
+                    Text immediately following `anchorText`, used to disambiguate
+                    between multiple occurrences. Requires `anchorText`.
               required:
                 - documentId
       responses: