Issue Comments And Agent Threads

Comment bodies

• Comment write endpoints accept plain text body
• Comment read endpoints return body as a rich-text document

GET /v1/issues/{issueKey}/comments

Requires issues:read.

Query parameters

Parameter	Type	Notes
cursor	string	Optional cursor
page_size	integer	Optional page size
parent_comment_id	string	Optional parent-comment filter
sort	string	Only created is accepted
direction	string	asc, ascending, desc, or descending

Example

curl "$API_BASE_URL/v1/issues/PLAT-142/comments?sort=created&direction=asc" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK:

{
  "results": [
    {
      "id": "comment_initial",
      "parentCommentId": "",
      "authorUserAccountId": "usr_01EXAMPLE",
      "authorDisplayName": "Alex Morgan",
      "authorAvatarUrl": "https://cdn.example.com/avatars/alex.png",
      "parentAuthorDisplayName": "",
      "body": {
        "schemaVersion": 1,
        "content": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Split auth, conventions, and endpoint groups."
                }
              ]
            }
          ]
        }
      },
      "canManage": true,
      "isEdited": false,
      "createdUtc": "2025-02-24T15:04:05Z",
      "updatedUtc": "2025-02-24T15:04:05Z"
    }
  ],
  "pagination": {
    "pageSize": 100,
    "cursor": "",
    "nextCursor": "",
    "hasMore": false,
    "returnedCount": 1,
    "totalCount": 1
  }
}

GET /v1/issues/{issueKey}/comments/{commentId}

Requires issues:read.

curl "$API_BASE_URL/v1/issues/PLAT-142/comments/comment_initial" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK:

{
  "id": "comment_initial",
  "parentCommentId": "",
  "authorUserAccountId": "usr_01EXAMPLE",
  "authorDisplayName": "Alex Morgan",
  "authorAvatarUrl": "https://cdn.example.com/avatars/alex.png",
  "parentAuthorDisplayName": "",
  "body": {
    "schemaVersion": 1,
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Split auth, conventions, and endpoint groups."
            }
          ]
        }
      ]
    }
  },
  "canManage": true,
  "isEdited": false,
  "createdUtc": "2025-02-24T15:04:05Z",
  "updatedUtc": "2025-02-24T15:04:05Z"
}

POST /v1/issues/{issueKey}/comments

Requires issues:write.

Request body

Field	Type	Required
parentCommentId	string	no
body	string	yes

Example

curl -X POST "$API_BASE_URL/v1/issues/PLAT-142/comments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Split auth, conventions, and endpoint groups."
  }'

Response 201 Created:

{
  "id": "comment_initial",
  "parentCommentId": "",
  "authorUserAccountId": "usr_01EXAMPLE",
  "authorDisplayName": "Alex Morgan",
  "authorAvatarUrl": "https://cdn.example.com/avatars/alex.png",
  "parentAuthorDisplayName": "",
  "body": {
    "schemaVersion": 1,
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Split auth, conventions, and endpoint groups."
            }
          ]
        }
      ]
    }
  },
  "canManage": true,
  "isEdited": false,
  "createdUtc": "2025-02-24T15:04:05Z",
  "updatedUtc": "2025-02-24T15:04:05Z"
}

PATCH /v1/issues/{issueKey}/comments/{commentId}

Requires issues:write.

Request body

Field	Type	Required
body	string	yes

Example

curl -X PATCH "$API_BASE_URL/v1/issues/PLAT-142/comments/comment_initial" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Split auth, conventions, endpoint groups, and mutation pages."
  }'

Response 200 OK:

{
  "id": "comment_initial",
  "parentCommentId": "",
  "authorUserAccountId": "usr_01EXAMPLE",
  "authorDisplayName": "Alex Morgan",
  "authorAvatarUrl": "https://cdn.example.com/avatars/alex.png",
  "parentAuthorDisplayName": "",
  "body": {
    "schemaVersion": 1,
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Split auth, conventions, endpoint groups, and mutation pages."
            }
          ]
        }
      ]
    }
  },
  "canManage": true,
  "isEdited": true,
  "createdUtc": "2025-02-24T15:04:05Z",
  "updatedUtc": "2025-02-24T15:18:42Z"
}

DELETE /v1/issues/{issueKey}/comments/{commentId}

Requires issues:write.

curl -X DELETE "$API_BASE_URL/v1/issues/PLAT-142/comments/comment_initial" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 204 No Content.

GET /v1/issues/{issueKey}/agent-thread

Requires issues:read.

curl "$API_BASE_URL/v1/issues/PLAT-142/agent-thread" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK:

{
  "id": "thread_main",
  "issueId": "issue_plat_142",
  "applicationId": "app_agent",
  "applicationInstallationId": "install_agent_platform",
  "agentUserAccountId": "usr_agent",
  "agentDisplayName": "Quantify Agent",
  "agentAvatarUrl": "https://cdn.example.com/avatars/agent.png",
  "agentPrincipalKind": 2,
  "status": 1,
  "lastMessagePreview": "Drafted the API docs structure and examples.",
  "lastMessageUtc": "2025-02-24T16:05:10Z",
  "lastMessageAuthorType": 2,
  "lastMessageType": 3,
  "currentTurnNumber": 6,
  "lastCompletedTurnNumber": 5,
  "messageCount": 14,
  "startedUtc": "2025-02-23T13:10:00Z"
}

GET /v1/issues/{issueKey}/agent-thread/messages

Requires issues:read.

curl "$API_BASE_URL/v1/issues/PLAT-142/agent-thread/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response 200 OK:

{
  "thread": {
    "id": "thread_main",
    "issueId": "issue_plat_142",
    "applicationId": "app_agent",
    "applicationInstallationId": "install_agent_platform",
    "agentUserAccountId": "usr_agent",
    "agentDisplayName": "Quantify Agent",
    "agentAvatarUrl": "https://cdn.example.com/avatars/agent.png",
    "agentPrincipalKind": 2,
    "status": 1,
    "lastMessagePreview": "Drafted the API docs structure and examples.",
    "lastMessageUtc": "2025-02-24T16:05:10Z",
    "lastMessageAuthorType": 2,
    "lastMessageType": 3,
    "currentTurnNumber": 6,
    "lastCompletedTurnNumber": 5,
    "messageCount": 14,
    "startedUtc": "2025-02-23T13:10:00Z"
  },
  "messages": [
    {
      "id": "msg_01",
      "threadId": "thread_main",
      "issueId": "issue_plat_142",
      "applicationId": "app_agent",
      "applicationInstallationId": "install_agent_platform",
      "agentUserAccountId": "usr_agent",
      "authorType": 2,
      "messageType": 3,
      "authorUserAccountId": "usr_agent",
      "authorDisplayName": "Quantify Agent",
      "authorAvatarUrl": "https://cdn.example.com/avatars/agent.png",
      "authorPrincipalKind": 2,
      "body": "Drafted the API docs structure and examples.",
      "turnNumber": 6,
      "replyToMessageId": "",
      "followUpActions": [
        {
          "name": "Review draft",
          "key": "review-draft",
          "color": "#2563eb"
        }
      ],
      "createdUtc": "2025-02-24T16:05:10Z"
    }
  ]
}

POST /v1/issues/{issueKey}/agent-thread/messages

Requires issues:write.

Request body

Field	Type	Required	Notes
body	string	yes	Message body
messageType	integer	no	See enum codes
turnNumber	integer	no	Optional turn number
replyToMessageId	string	no	Optional reply target
followUpActions	array	no	Array of { name, key, color }

Example

curl -X POST "$API_BASE_URL/v1/issues/PLAT-142/agent-thread/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Drafted the API docs structure and examples.",
    "messageType": 3,
    "turnNumber": 6,
    "followUpActions": [
      {
        "name": "Review draft",
        "key": "review-draft",
        "color": "#2563eb"
      }
    ]
  }'

Response 201 Created:

{
  "id": "msg_01",
  "threadId": "thread_main",
  "issueId": "issue_plat_142",
  "applicationId": "app_agent",
  "applicationInstallationId": "install_agent_platform",
  "agentUserAccountId": "usr_agent",
  "authorType": 2,
  "messageType": 3,
  "authorUserAccountId": "usr_agent",
  "authorDisplayName": "Quantify Agent",
  "authorAvatarUrl": "https://cdn.example.com/avatars/agent.png",
  "authorPrincipalKind": 2,
  "body": "Drafted the API docs structure and examples.",
  "turnNumber": 6,
  "replyToMessageId": "",
  "followUpActions": [
    {
      "name": "Review draft",
      "key": "review-draft",
      "color": "#2563eb"
    }
  ],
  "createdUtc": "2025-02-24T16:05:10Z"
}