Issue Time Tracking

This sub-resource let you operate work items of an issue.

Resource	`/api/issues/<issueID>/timeTracking/workItems`
Returned entity	IssueWorkItem. For the description of the entity attributes, see Supported Fields section.
Supported methods	`GET`: read time tracking records of an issue. `POST`: add a new work item to an issue.
Sub-resources	`/api/issues/<issueID>/timeTracking/workItems/<workItemID>`: operations with a specific work item.

Supported Fields

This table describes attributes of the IssueWorkItem entity.

To receive an attribute in the response from server, specify it explicitly in the fields parameter of a request.
To update an attribute, provide it in the body of a POST request.

Field	Type	Description
created	Long	Read-only. Timestamp of the moment when the work item is created.
date	Long	Stores the timestamp of the date for which the work item is reported.
duration	PeriodValue	Stores the duration of the work item.
issue	Issue	Stores attributes of the issue to which the work item is attached.
updated	Long	Read-only. Timestamp of the moment when the work item was last updated.
author	User	Stores attributes of the user account that is the author of the work item.
creator	User	Read-only. Stores the attributes of the user account that reported the work item.
id	String	An entity ID of the work item.
issueTimeTracker	IssueTimeTracker	Time tracking settings of an issue. Stores the current status of time tracking in a project to which the issue belongs and the list of work item drafts.
text	String	A comment that is added with the work item.
textPreview	String!	Parsed preview of the comment text.
type	WorkItemType	A type of the work item.
usesMarkdown	Boolean	Stores the format of the comment text. When `true`, the comment is processed as Markdown formatted text. Otherwise, the comment is processed as YouTrack Wiki formatted.

Read Work Items of an Issue

Request syntax:

GET /api/issues/<issueID>/timeTracking/workItems?[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 entity attributes that should be returned in the response. If no fields specified, only an entity 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-35/timeTracking/workItems?fields=author%28id,name%29,creator%28id,name%29,date,duration%28id,minutes,presentation%29,id,name,text,type%28id,name%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

[
    {
        "duration": {
            "presentation": "5h",
            "minutes": 300,
            "id": "PT5H"
        },
        "date": 1536278400000,
        "text": "almost there",
        "type": {
            "name": "Testing",
            "id": "65-1"
        },
        "creator": {
            "name": "John Smith",
            "id": "1-1"
        },
        "author": {
            "name": "John Smith",
            "id": "1-1"
        },
        "id": "115-0"
    },
    {
        "duration": {
            "presentation": "1h",
            "minutes": 60,
            "id": "PT1H"
        },
        "date": 1538956800000,
        "text": "added a document for internal parameters. check wiki for details",
        "type": {
            "name": "Documentation",
            "id": "65-2"
        },
        "creator": {
            "name": "John Doe",
            "id": "1-2"
        },
        "author": {
            "name": "Jane Doe",
            "id": "1-3"
        },
        "id": "115-2"
    }
]

Add a Work Item to an Issue

Request syntax

POST /api/issues/<issueID>/timeTracking/workItems[?{fields}

Request parameters

Parameter	Type	Description
issueID	string	A unique ID of an issue to add a work item to. 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 IssueWorkItem attributes that should be returned in the response. If no fields specified, only an entity ID is returned.

Sample request

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/issues/2-35/timeTracking/workItems?fields=author%28id,login,name%29,creator%28id,login,name%29,date,duration%28id,minutes,presentation%29,id,name,text,type%28id,name%29,usesMarkdown' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{"date":1539000000000,"author":{"id":"1-4"},"duration":{"presentation":"45m"},"type":{"id":"65-2"},"text":"added a document for internal parameters"}'

Sample response body

{
    "duration": {
        "presentation": "45m",
        "minutes": 45,
        "id": "PT45M"
    },
    "date": 1538956800000,
    "text": "added a document for internal parameters",
    "type": {
        "name": "Documentation",
        "id": "65-2"
    },
    "creator": {
        "login": "john.doe",
        "name": "John Doe",
        "id": "1-2"
    },
    "author": {
        "login": "Jane_Smith",
        "name": "Jane Smith",
        "id": "1-4"
    },
    "usesMarkdown": true,
    "id": "115-2"
}

Operations with a Work Item

Read a Work Item

Request syntax

GET /api/issues/<issueID>/timeTracking/workItems/<workItemID>?[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).
workItemID	string	An entity ID of a work item to get.
fields	string	A list of IssueWorkItem attributes that should be returned in the response. If no fields specified, only an entity ID is returned.

Sample request

curl -X GET \
'https://example.myjetbrains.com/youtrack/api/issues/2-35/timeTracking/workItems/115-2?fields=author%28id,login,name%29,creator%28id,login,name%29,date,duration%28id,minutes,presentation%29,id,name,text,type%28id,name%29,usesMarkdown' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

Sample response body

{
    "duration": {
        "presentation": "45m",
        "minutes": 45,
        "id": "PT45M"
    },
    "date": 1538956800000,
    "text": "added a document for internal parameters",
    "type": {
        "name": "Documentation",
        "id": "65-2"
    },
    "creator": {
        "login": "john.doe",
        "name": "John Doe",
        "id": "1-2"
    },
    "author": {
        "login": "Jane_Smith",
        "name": "Jane Smith",
        "id": "1-4"
    },
    "usesMarkdown": true,
    "id": "115-2"
}

Update a Work Item

Request syntax

POST /api/issues/<issueID>/timeTracking/workItems/<workItemID>?[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).
workItemID	string	An entity ID of a work item to update.
fields	string	A list of IssueWorkItem attributes that should be returned in the response. If no fields specified, only an entity ID is returned.

Sample request

curl -X POST \
'https://example.myjetbrains.com/youtrack/api/issues/2-35/timeTracking/workItems/115-2?fields=author%28id,name%29,creator%28id,name%29,date,duration%28id,minutes,presentation%29,id,name,text,type%28id,name%29' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{"author":{"id":"1-3"},"duration":{"minutes":60},"text":"added a document for internal parameters. check wiki for details"}'

Sample response body

{
    "duration": {
        "presentation": "1h",
        "minutes": 60,
        "id": "PT1H"
    },
    "date": 1538956800000,
    "text": "added a document for internal parameters. check wiki for details",
    "type": {
        "name": "Documentation",
        "id": "65-2"
    },
    "creator": {
        "name": "John Doe",
        "id": "1-2"
    },
    "author": {
        "name": "Jane Doe",
        "id": "1-3"
    },
    "id": "115-2"
}

Delete a Work Item

Request syntax

DELETE /api/issues/<issueID>/timeTracking/workItems/<workItemID>

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).
workItemID	string	An entity ID of a work item to delete.

Sample request

curl -X DELETE \
https://example.myjetbrains.com/youtrack/api/issues/2-35/timeTracking/workItems/115-4 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json'

For a successful DELETE request, the server sends back a response with the 200 OK status code and an empty body.

Last modified: 7 March 2019