Developer Portal for YouTrack and Hub 2021.1 Help

Get Issue History using REST API

Use Case:

Use the REST API to get a history of changes of a specific issue.

Summary

To read history of changes for a specific issue, you need to use the following resource:

/api/issues/{issueID}/activities

Yes, it's that simple. One GET request to a the mentioned resource. What you need to pay attention to, is the request parameters:

  • categories: This is the mandatory parameter that filters found activities (history events) by categories. So, you must specify at least one category here for the request. For the list of possible categories, read ActivityCategory page.

  • fields: as for any other request in YouTrack, this parameter lists attributes that you want server to return in response. For issue history, we recommend that you ask for the following attributes:

    • author to see who made the change

    • target to see what was changed.

    Please note that supported attributes differ depending on the actual type of the activity that you request with the categories parameter. See the ActivityItem section for all supported activity items and their attributes.

  • {issue ID} represents the unique ID of the target issue. You can identify the issue by its entityID (for example, 2-32) or human-readable ID as you see it in UI (for example, SP-32).

For this usecase we will omit a step-by-step procedure, as it seems redundant. Let's just see a sample request.

Sample Request

In this sample request we instruct server to return history of the issue 'SP-32' and return the following categories of changes:

  • IssueCreatedCategory - when the issue was created.

  • CommentsCategory - changes in comments to this issue.

  • IssueVisibilityCategory - changes in visibility settings of the issue, whether the visibility was updated and how.

As for attributes, let's request those that we recommended above: author and target, and timestamp - to know when the change happened. As we want to see changes in issue visibility, let's also add added and removed attributes to see who was added or removed from the visibility settings of the issue. So, our fields parameter looks as follows:

fields=author(name,login),timestamp,target(id,text),added(name,login),removed(name,login)

Here's the complete resulting request:

curl -L -X GET 'https://example.myjetbrains.com/youtrack/api/issues/SP-32/activities?categories=CommentsCategory,IssueCreatedCategory,IssueVisibilityCategory'&fields=author(name,login),timestamp,target(id,text),added(name,login),removed(name,login) \ -H 'Accept: application/json' \ -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7'

To such request, server would return the following data:

[ { "target": { "id": "2-31", "$type": "Issue" }, "removed": [], "added": [], "author": { "login": "john.doe", "name": "John Doe", "$type": "User" }, "timestamp": 1533139032010, "$type": "IssueCreatedActivityItem" }, { "removed": [], "added": [ { "$type": "IssueComment" } ], "author": { "login": "jane.doe", "name": "Jane Doe", "$type": "User" }, "timestamp": 1533214812208, "target": { "text": "@john.doe let's update the summary and description", "id": "4-0", "$type": "IssueComment" }, "$type": "CommentActivityItem" }, { "removed": [], "added": [ { "$type": "IssueComment" } ], "author": { "login": "john.doe", "name": "John Doe", "$type": "User" }, "timestamp": 1533221614364, "target": { "text": "okay, let's do it, @jane.doe. By the way, I'm updating this comment using REST.", "id": "4-2", "$type": "IssueComment" }, "$type": "CommentActivityItem" }, { "removed": [], "added": [ { "name": "Sample Project Team", "$type": "UserGroup" } ], "author": { "login": "john.doe", "name": "John Doe", "$type": "User" }, "timestamp": 1535649875680, "target": { "id": "2-31", "$type": "Issue" }, "$type": "VisibilityGroupActivityItem" } ]
Last modified: 8 April 2021