Adding a comment

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

POST

https://api.tracker.yandex.net/v3/entities/<entity_type>/<entity_ID>/comments

Query format

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

To add a comment to an entity, use an HTTP POST request. In the request body, specify the parameters in JSON format.

POST /v3/entities/<entity_type>/<entity_ID>/comments
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

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

Headers

Host: Address of the node that provides the API.
Authorization: Authorization token about these formats:
- OAuth <OAuth_token>: For authorization using the OAuth 2.0 protocol. Learn more
- Bearer <IAM_token>: For authorization using an IAM token, if a Yandex Cloud Organization organization is linked to Tracker. Learn more
X-Org-ID or X-Cloud-Org-ID: Organization ID.
- Use the X-Org-ID header if a Tracker organization is linked to Yandex 360 for Business.
- Use the X-Cloud-Org-ID header if a Tracker organization is linked to Yandex Cloud Organization.
To get the organization ID, go to Administration → Organizations and copy the value from the ID field.

Resource

Parameter	Description	Data type
<entity_type>	Entity type: project portfolio goal	String
<entity_ID>	Entity ID. To get the ID, see the entity list. You can use the `id` or `shortId` parameter as the ID.	String

Request parameters

Additional parameters

Parameter	Description	Data type
isAddToFollowers	Adding a comment author to followers. The default value is `true`.	Boolean
notify	Notify the users specified in the Author, Lead, Participants, Customers, and Followers fields. The default value is `true`.	Boolean
notifyAuthor	Notify the author of the changes. The default value is `false`.	Boolean
expand	Additional information to include in 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	IDs of temporary files that will be added as attachments.	Array of strings
summonees	IDs or usernames of summoned 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 /v3/entities/project/<project_ID>/comments
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth_token>
X-Org-ID or X-Cloud-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/v3/entities/project/6586d6fee2b9ef74********/comments/22",
    "id": 22,
    "longId": "65a1ba7b46b9746d********",
    "text": "Comment text.",
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/19********",
        "id": "19********",
        "display": "Full name",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": "15********"
    },
    "updatedBy": {
        "self": "https://api.tracker.yandex.net/v3/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/v3/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	Map item
updatedBy	Object with information about the last user to have updated the comment	Map item
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.	String
display	Displayed user name	String
passportUid	Unique ID of the user account in the Yandex 360 for Business organization and Yandex ID.	Number
cloudUid	Unique user ID in Yandex Cloud Organization	String

updatedBy object fields

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

Was the article helpful?

Getting entity event history

Editing a comment