Adding a comment

Written by

Updated at May 6, 2024

Request format
Response format

The request allows you to add a comment to an entity.

Request format

Before making a request, get permission to access the API.

To add a comment to an entity, use an HTTP POST request. Request parameters are provided in the request body in JSON format.

POST /v2/entities/<entity_type>/<entity_ID>/comments
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
  "text": "<comment_text>",
  "summonees": ["<summonee_ID_or_login>"]
}

Headers

Host

Address of the node that provides the API:
```
https://api.tracker.yandex.net
```
Authorization

OAuth token in OAuth <OAuth_token> format, e.g.:
```
OAuth 0c4181a7c2cf4521964a72ff********
```
X-Org-ID or X-Cloud-Org-ID

Organization ID. You can find it out on the Tracker organizations page.
- If a Yandex 360 for Business organization is the only one linked to Tracker, the X-Org-ID header is used.
- If a Yandex Cloud Organization organization is the only one linked to Tracker, the X-Cloud-Org-ID header is used.
- If both Yandex 360 for Business and Yandex Cloud Organization organizations are linked to Tracker at the same time, the X-Org-ID header and the Yandex 360 for Business organization ID are used.

Resource

Parameter	Description	Data type
<entity_type>	Entity type: Project for a project Portfolio for a portfolio	String
<entity_ID>	Entity ID. To get the ID, see the entity list.	String
<project_or_portfolio_ID>	Project or portfolio ID (the `shortId` value). You can use it instead of the entity ID in the request.	String

Warning

Entity ID is not the same as project or portfolio ID.

Request parameters

Additional parameters

Parameter	Description	Data type
isAddToFollowers	Adding a comment author to followers. The default value is `true`.	Logical
notify	Notify the users specified in the Author, Responsible, Members, Clients, and Followers fields. The default value is `true`.	Logical
notifyAuthor	Notify the author of the changes. The default value is `false`.	Logical
expand	Additional information to be included into the response: `all`: All `html`: Comment HTML markup `attachments`: Attached files `reactions`: Reactions to a comment	String

Request body parameters

The request body contains the information needed to add a comment:

Required parameters

Parameter	Description	Data type
text	Text of the comment.	String

Additional parameters

Parameter	Description	Data type
attachmentIds	List of attachment IDs.	Array of strings
summonees	IDs or usernames of invited users.	Array of objects or strings
maillistSummonees	List of mailing lists mentioned in the comment.	Array of strings

Example: Adding a comment

An HTTP POST method is used.

A comment is added to the entity (project): Comment text.

The user is summoned.
POST /v2/entities/project/<project_ID>/comments
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID: <organization ID>

{
   "text":"<comment_text>",
   "summonees": [<user_ID>]
}

Response format

Request executed successfully

Request failed

If the request is successful, the API returns a response with code 201 Created.

The response body contains information about the comment in JSON format.

{
    "self": "https://api.tracker.yandex.net/v2/entities/project/6586d6fee2b9ef74********/comments/22",
    "id": 22,
    "longId": "65a1ba7b46b9746d********",
    "text": "Comment text.",
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v2/users/19********",
        "id": "19********",
        "display": "Full Name",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": "15********"
    },
    "updatedBy": {
        "self": "https://api.tracker.yandex.net/v2/users/19********",
        "id": "19********",
        "display": "Full Name",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": "15********"
    },
    "createdAt": "2024-01-12T22:17:31.176+0000",
    "updatedAt": "2024-01-12T22:17:31.176+0000",
    "summonees": [
        {
            "self": "https://api.tracker.yandex.net/v2/users/19********",
            "id": "19********",
            "display": "Full Name",
            "cloudUid": "ajeppa7dgp32********",
            "passportUid": "12********"
        }
    ],
    "version": 1,
    "type": "standard",
    "transport": "internal"
}

Response parameters

Parameter	Description	Data type
self	Link to the comment object.	String
id	Comment ID.	Number
longId	Comment ID as a string.	String
text	Text of the comment.	String
textHtml	Comment HTML markup.	String
attachments	Attached files.	String
createdBy	Object with information about the author of the comment.	Object
updatedBy	Object with information about the last user to have updated the comment.	Object
createdAt	Comment creation date and time in the format: `YYYY-MM-DDThh:mm:ss.sss±hhmm`	String
updatedAt	Comment update date and time in the format: `YYYY-MM-DDThh:mm:ss.sss±hhmm` .	String
summonees	List of users summoned in comments.	List of objects
maillistSummonees	List of mailing lists mentioned in the comment.	List of objects
version	Comment version. Each update increases the comment's version number.	Number
type	Comment type: `standard`: Comment sent via the Tracker interface. `incoming`: Comment created from an incoming message. `outcoming`: Comment created from an outgoing message.	String
transport	Method of adding a comment: `internal`: Via the Tracker interface. `email`: Via email.	String

createdBy object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user.	String
id	User ID.	Number
display	Displayed user name.	String
cloudUid	User unique ID in Yandex Cloud Organization.	String
passportUid	Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID.	String

updatedBy object fields

Parameter	Description	Data type
self	Address of the API resource with information about the user.	String
id	User ID.	Number
display	Displayed user name.	String
cloudUid	User unique ID in Yandex Cloud Organization.	String
passportUid	Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID.	String

If the request is processed incorrectly, the API returns a response with an error code:

400: One or more request parameters have an invalid value.

404: The requested object was not found. You may have specified an invalid object ID or key.

422: JSON validation error, the request is rejected.

Adding a comment

Request formatRequest format

Response formatResponse format

Was the article helpful?

Request format

Response format