Cloud

Jira Cloud platform / Reference / REST API v3

Issue comments

This resource represents issue comments. Use it to:

get, create, update, and delete a comment from an issue.
get all comments from issue.
get a list of comments by comment ID.

Operations

POST/rest/api/3/comment/list GET/rest/api/3/issue/{issueIdOrKey}/comment POST/rest/api/3/issue/{issueIdOrKey}/comment GET/rest/api/3/issue/{issueIdOrKey}/comment/{id}PUT/rest/api/3/issue/{issueIdOrKey}/comment/{id}DEL/rest/api/3/issue/{issueIdOrKey}/comment/{id}

POST

Get comments by IDs

Returns a paginated list of comments specified by a list of comment IDs.

This operation can be accessed anonymously.

Permissions required: Comments are returned where the user:

has Browse projects project permission for the project containing the comment.
If issue-level security is configured, issue-level security permission to view the issue.
If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:delete:comment.property:jira, read:avatar:jira, read:comment:jira, read:group:jira, read:project-role:jira ...(Show more)

Connect app scope required: READ

Request

Query parameters

expand

string

Request bodyapplication/json

The list of comment IDs.

ids

array<integer>

Required

Responses

Returned if the request is successful.

application/json

PageBeanComment

A page of items.

POST/rest/api/3/comment/list

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "ids": [
    1,
    2,
    5,
    10
  ]
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/comment/list`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "isLast": true,
  "maxResults": 1048576,
  "startAt": 0,
  "total": 1,
  "values": [
    {
      "author": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      },
      "body": {
        "type": "doc",
        "version": 1,
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
              }
            ]
          }
        ]
      },
      "created": "2021-01-17T12:34:00.000+0000",
      "id": "10000",
      "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
      "updateAuthor": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      },
      "updated": "2021-01-18T23:45:00.000+0000",
      "visibility": {
        "identifier": "Administrators",
        "type": "role",
        "value": "Administrators"
      }
    }
  ]
}

GET

Get comments

Returns all comments for an issue.

This operation can be accessed anonymously.

Permissions required: Comments are included in the response where the user has:

Browse projects project permission for the project containing the comment.
If issue-level security is configured, issue-level security permission to view the issue.
If the comment has visibility restrictions, belongs to the group or has the role visibility is role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:comment:jira, read:comment.property:jira, read:group:jira, read:project:jira, read:project-role:jira ...(Show more)

Connect app scope required: READ

Request

Path parameters

issueIdOrKey

string

Required

Query parameters

startAt

integer

maxResults

integer

orderBy

string

expand

string

Responses

Returned if the request is successful.

application/json

PageOfComments

A page of comments.

GET/rest/api/3/issue/{issueIdOrKey}/comment

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/comment`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "comments": [
    {
      "author": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      },
      "body": {
        "type": "doc",
        "version": 1,
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
              }
            ]
          }
        ]
      },
      "created": "2021-01-17T12:34:00.000+0000",
      "id": "10000",
      "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
      "updateAuthor": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
      },
      "updated": "2021-01-18T23:45:00.000+0000",
      "visibility": {
        "identifier": "Administrators",
        "type": "role",
        "value": "Administrators"
      }
    }
  ],
  "maxResults": 1,
  "startAt": 0,
  "total": 1
}

POST

Add comment

Adds a comment to an issue.

This operation can be accessed anonymously.

Permissions required:

Browse projects and Add comments project permission for the project that the issue containing the comment is in.
If issue-level security is configured, issue-level security permission to view the issue.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:read:comment:jira, read:comment.property:jira, read:group:jira, read:project:jira, read:project-role:jira ...(Show more)

Connect app scope required: WRITE

Request

Path parameters

issueIdOrKey

string

Required

Query parameters

expand

string

Request bodyapplication/json

body

any

properties

array<EntityProperty>

visibility

Visibility

Additional Properties

any

Responses

Returned if the request is successful.

application/json

Comment

A comment.

POST/rest/api/3/issue/{issueIdOrKey}/comment

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "body": {
    "content": [
      {
        "content": [
          {
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.",
            "type": "text"
          }
        ],
        "type": "paragraph"
      }
    ],
    "type": "doc",
    "version": 1
  },
  "visibility": {
    "identifier": "Administrators",
    "type": "role",
    "value": "Administrators"
  }
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/comment`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

201Response

{
  "author": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
          }
        ]
      }
    ]
  },
  "created": "2021-01-17T12:34:00.000+0000",
  "id": "10000",
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
  "updateAuthor": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  "updated": "2021-01-18T23:45:00.000+0000",
  "visibility": {
    "identifier": "Administrators",
    "type": "role",
    "value": "Administrators"
  }
}

GET

Get comment

Returns a comment.

This operation can be accessed anonymously.

Permissions required:

Browse projects project permission for the project containing the comment.
If issue-level security is configured, issue-level security permission to view the issue.
If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:comment:jira, read:comment.property:jira, read:group:jira, read:project:jira, read:project-role:jira ...(Show more)

Connect app scope required: READ

Request

Path parameters

issueIdOrKey

string

Required

string

Required

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

Comment

A comment.

GET/rest/api/3/issue/{issueIdOrKey}/comment/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/comment/{id}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "author": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
          }
        ]
      }
    ]
  },
  "created": "2021-01-17T12:34:00.000+0000",
  "id": "10000",
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
  "updateAuthor": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  "updated": "2021-01-18T23:45:00.000+0000",
  "visibility": {
    "identifier": "Administrators",
    "type": "role",
    "value": "Administrators"
  }
}

PUT

Update comment

Updates a comment.

This operation can be accessed anonymously.

Permissions required:

Browse projects project permission for the project that the issue containing the comment is in.
If issue-level security is configured, issue-level security permission to view the issue.
Edit all comments project permission to update any comment or Edit own comments to update comment created by the user.
If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:read:comment:jira, read:comment.property:jira, read:group:jira, read:project:jira, read:project-role:jira ...(Show more)

Connect app scope required: WRITE

Request

Path parameters

issueIdOrKey

string

Required

string

Required

Query parameters

notifyUsers

boolean

overrideEditableFlag

boolean

expand

string

Request bodyapplication/json

body

any

properties

array<EntityProperty>

visibility

Visibility

Additional Properties

any

Responses

Returned if the request is successful.

application/json

Comment

A comment.

PUT/rest/api/3/issue/{issueIdOrKey}/comment/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "body": {
    "content": [
      {
        "content": [
          {
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper.",
            "type": "text"
          }
        ],
        "type": "paragraph"
      }
    ],
    "type": "doc",
    "version": 1
  },
  "visibility": {
    "identifier": "Administrators",
    "type": "role",
    "value": "Administrators"
  }
}`;

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/comment/{id}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "author": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  "body": {
    "type": "doc",
    "version": 1,
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
          }
        ]
      }
    ]
  },
  "created": "2021-01-17T12:34:00.000+0000",
  "id": "10000",
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
  "updateAuthor": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g"
  },
  "updated": "2021-01-18T23:45:00.000+0000",
  "visibility": {
    "identifier": "Administrators",
    "type": "role",
    "value": "Administrators"
  }
}

DEL

Delete comment

Deletes a comment.

Permissions required:

Browse projects project permission for the project that the issue containing the comment is in.
If issue-level security is configured, issue-level security permission to view the issue.
Delete all comments project permission to delete any comment or Delete own comments to delete comment created by the user,
If the comment has visibility restrictions, the user belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:delete:comment:jira, delete:comment.property:jira

Connect app scope required: DELETE

Request

Path parameters

issueIdOrKey

string

Required

string

Required

Responses

Returned if the request is successful.

DEL/rest/api/3/issue/{issueIdOrKey}/comment/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/3/issue/{issueIdOrKey}/comment/{id}`, {
  method: 'DELETE'
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());