Issue Comments
This sub-resource let you operate comments of an issue.
Resource |
/api/issues/<issueID>/comments |
Returned entity | IssueComment. For the description of the entity attributes, see Supported Fields section. |
Supported methods | |
Sub-resource | /api/issues/<issueID>/comments/<commentID> |
Supported Fields
The returned entity contains the following attributes that you can require with the fields
parameter of a request or provide in a request body.
Field | Type | Description |
---|---|---|
author | Stores the data of a user account that authored the comment. | |
deleted | Boolean | When true, the comment was deleted from the issue. Otherwise, the comment is present in te system. |
issue | Stores attributes of an issue to which this comment is added. | |
attachments | MutableCollection | Stores the attachments linked to the comment. |
created | Long | Stores the timestamp of the moment when the comment was added created. |
id | String | Stores the ID of the comment. |
text | String | Stores the text content of the comment. |
textPreview | String! | Stores the parsed preview of the comment. |
updated | Long | Stores the timestamp of the comment's last update. |
usesMarkdown | Boolean | When true, the comment is processed as a text formatted with Markdown. |
visibility | Stores visibility settings of the comment. For details about visibility settings, see Visibility Settings. |
Read Comments of a Specific Issue
Request syntax:
GET /api/issues/<issueID>/comments?[fields=<fields>&$top&$skip]
Request parameters:
Parameter | Type | Description |
---|---|---|
issueID | string | A unique ID of an issue to get. You can provide it either as an issue entity id (for example, 42-44) or an issue id in project (for example, TST-33). |
fields | string | A list of IssueComment attributes that should be returned in the response. If no fields specified, only comment's ID is returned. |
$skip | int | Optional. Lets you set a number of returned entities to skip before returning the first one. |
$top | int | Optional. Lets you specify the maximum number of entries that are returned in the response. |
Sample request:
curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues/2-31/comments?fields=id,author%28login,name,id%29,deleted,text,updated,visibility%28permittedGroups%28name,id%29,permittedUsers%28id,name,login%29%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
Response body:
[
{
"author": {
"login": "jane.doe",
"name": "Jane Doe",
"id": "1-3"
},
"deleted": false,
"updated": null,
"text": "@john.doe let's update the summary and description",
"visibility": {
"permittedGroups": [
{
"name": "Sample Project Team",
"id": "3-2"
}
],
"permittedUsers": [],
"$type": "jetbrains.charisma.persistent.visibility.LimitedVisibility"
},
"id": "4-0"
},
{
"author": {
"login": "john.doe",
"name": "John Doe",
"id": "1-2"
},
"deleted": false,
"updated": 1533223079255,
"text": "okay, let's do it, @jane.doe. I am btw updating this from rest",
"visibility": {
"$type": "jetbrains.charisma.persistent.visibility.UnlimitedVisibility"
},
"id": "4-2"
}
]
Add a Comment to a Specific Issue
Create a new comment for an issue with a specific ID.
Request syntax:
POST /api/issues/<issueID>/comments?[fields=<fields>]
Request parameters:
Parameter | Type | Description |
---|---|---|
issueID | string | A unique ID of an issue to get. You can provide it either as an issue entity id (for example, 42-44) or an issue id in project (for example, TST-33). |
fields | string | A list of IssueComment attributes that should be returned in the response. If no fields specified, only comment's ID is returned. |
Sample request:
curl -X POST \
'https://example.myjetbrains.com/youtrack/api/issues/2-6/comments?fields=id,author%28login,name,id%29,deleted,text,updated,visibility%28permittedGroups%28name,id%29,permittedUsers%28id,name,login%29%29' \
-H 'Accept: application/json' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"text": "Disregard the previous comment. The problem still requires investigation.",
"visibility": {
"permittedGroups":[{"id":"3-2"}],
"$type": "jetbrains.charisma.persistent.visibility.LimitedVisibility"
}
}'
Sample response body:
{
"deleted": false,
"author": {
"login": "john.doe",
"name": "John Doe",
"id": "1-2"
},
"visibility": {
"permittedUsers": [],
"permittedGroups": [
{
"name": "Sample Project Team",
"id": "3-2"
}
],
"$type": "jetbrains.charisma.persistent.visibility.LimitedVisibility"
},
"text": "Looks like this issue is obsolete.",
"updated": null,
"id": "4-3"
}
Operations with a Specific Comment
Resource |
/api/issues/<issueID>/comments/<commentID> |
Returned entity | IssueComment. For the description of the entity attributes, see Supported Fields section. |
Supported methods |
Read an Existing Comment
Request syntax:
GET /api/issues/<issueID>/comments/<commentID>?[fields=<fields>]
Request parameters:
Parameter | Type | Description |
---|---|---|
issueID | string | A unique ID of an issue. You can provide it either as an issue entity id (for example, 42-44) or an issue id in project (for example, TST-33). |
commentID | string | A unique ID of a comment to get. |
fields | string | A list of IssueComment attributes that should be returned in the response body. If no fields specified, only comment's ID is returned. |
Sample request:
curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues/2-6/comments/4-3?fields=id,author%28login,name,id%29,deleted,text,updated,visibility%28permittedGroups%28name,id%29,permittedUsers%28id,name,login%29%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'
Sample response body:
{
"deleted": false,
"author": {
"login": "john.doe",
"name": "John Doe",
"id": "1-2"
},
"visibility": {
"permittedUsers": [],
"permittedGroups": [
{
"name": "Sample Project Team",
"id": "3-2"
}
],
"$type": "jetbrains.charisma.persistent.visibility.LimitedVisibility"
},
"text": "Looks like this issue is obsolete.",
"updated": null,
"id": "4-3"
}
Update an Existing Comment
Update any parameter of an existing comment with a specific ID.
Request syntax:
POST /api/issues/<issueID>/comments/<commentID>?[fields=<fields>]
Request parameters:
Parameter | Type | Description |
---|---|---|
issueID | string | A unique ID of an issue. You can provide it either as an issue entity id (for example, 42-44) or an issue id in project (for example, TST-33). |
commentID | string | A unique ID of a comment to get. |
fields | string | A list of IssueComment attributes that should be returned in the response body. If no fields specified, only comment's ID is returned. |
Sample request:
curl -X POST \
'https://example.myjetbrains.com/youtrack/api/issues/2-31/comments/4-2/?fields=id,author%28login,name,id%29,deleted,text,updated,visibility%28permittedGroups%28name,id%29,permittedUsers%28id,name,login%29%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Content-Type: application/json' \
-d '{
"text": "okay, let'\''s do it, @jane.doe. By the way, I'\''m updating this comment using REST.",
"visibility": {
"permittedGroups":[{"id":"3-2"}],
"$type": "jetbrains.charisma.persistent.visibility.LimitedVisibility"
}
}'
Sample response body:
{
"deleted": false,
"author": {
"login": "john.doe",
"name": "John Doe",
"id": "1-2"
},
"visibility": {
"permittedUsers": [],
"permittedGroups": [
{
"name": "Sample Project Team",
"id": "3-2"
}
],
"$type": "jetbrains.charisma.persistent.visibility.LimitedVisibility"
},
"text": "okay, let's do it, @jane.doe. By the way, I'm updating this comment using REST.",
"updated": 1535542466727,
"id": "4-2"
}
Delete an Existing Comment
Delete an existing comment with the specific ID.
Request syntax:
DELETE /api/issues/<issueID>/comments/<commentID>
Request parameters
Parameter | Type | Description |
---|---|---|
issueID | string | A unique ID of an issue. You can provide it either as an issue entity id (for example, 42-44) or an issue id in project (for example, TST-33). |
commentID | string | A unique ID of a comment to delete. |
Sample request:
curl --request DELETE \
--url https://example.myjetbrains.com/youtrack/api/issues/2-7/comments/4-5 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json'
Sample response body:
For a successful DELETE
request, the server sends back a response with the 200 OK
code and an empty body.