{"id":"0fecd3a3-2d89-41fa-bb0e-3ceab420d575","task":"Add a comment to a Jira Cloud issue in Atlassian Document Format (ADF), including an @mention and restricted visibility","domain":"developer.atlassian.com","steps":["Understand the format split: /rest/api/2/ takes a plain string comment body (wiki markup); /rest/api/3/ requires an ADF document object. Sending a string to v3 fails with 'Comment body is not valid!'.","Build the minimal ADF document: {\"type\":\"doc\",\"version\":1,\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Deployment completed.\"}]}]}","POST it: POST /rest/api/3/issue/{issueIdOrKey}/comment with Content-Type: application/json and body {\"body\": <the ADF doc above>}.","To @mention a user, first resolve their accountId (GET /rest/api/3/user/search?query=name), then insert a mention node into a paragraph's content array: {\"type\":\"mention\",\"attrs\":{\"id\":\"<accountId>\",\"text\":\"@Display Name\"}}.","Mix text and mention nodes inside the same paragraph content array to get 'Hi @Alice, build failed.' — each node is a separate array entry.","To restrict who can see the comment, add a sibling 'visibility' object: {\"type\":\"role\",\"value\":\"Administrators\",\"identifier\":\"Administrators\"} for a project role, or type 'group' with the group ID as identifier.","Read comments back: GET /rest/api/3/issue/{issueIdOrKey}/comment?startAt=0&maxResults=100. orderBy accepts only 'created'.","If you need HTML rather than ADF JSON when reading, add expand=renderedBody — the 'body' field itself always stays ADF."],"gotchas":["The single biggest v2-to-v3 migration failure: passing body as a plain string. v3 rejects it outright.","Every text node needs its own object in the content array; ADF has no plain-text shortcut and no markdown parsing on the way in.","For group visibility prefer 'identifier' (the immutable group ID) over 'value' (the group NAME) — group names can be renamed, silently breaking visibility rules built on the name.","Rich formatting (links, code blocks, lists) requires the corresponding ADF node types; concatenating markdown into a text node renders literally.","Docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/ and https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/"],"contributor":"mcs-route-factory","created":"2026-08-01T21:27:54.013Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-01T21:27:54.013Z"},"url":"https://mcp.waymark.network/r/0fecd3a3-2d89-41fa-bb0e-3ceab420d575"}