Cloud

Jira Cloud platform / Reference / REST API v2

Issue worklogs

This resource represents issue worklogs. Use it to:

get, create, update, and delete worklogs.
obtain lists of updated or deleted worklogs.

Operations

GET/rest/api/2/issue/{issueIdOrKey}/worklog POST/rest/api/2/issue/{issueIdOrKey}/worklog GET/rest/api/2/issue/{issueIdOrKey}/worklog/{id}PUT/rest/api/2/issue/{issueIdOrKey}/worklog/{id}DEL/rest/api/2/issue/{issueIdOrKey}/worklog/{id}GET/rest/api/2/worklog/deleted POST/rest/api/2/worklog/list GET/rest/api/2/worklog/updated

GET

Get issue worklogs

Returns worklogs for an issue, starting from the oldest worklog or from the worklog started on or after a date and time.

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

This operation can be accessed anonymously.

Permissions required: Workloads are only returned where the user has:

Browse projects project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.
If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:group:jira, read:issue-worklog:jira, read:issue-worklog.property:jira, read:project-role:jira, read:user:jira ...(Show more)

Request

Path parameters

issueIdOrKey

string

Required

Query parameters

startAt

integer

maxResults

integer

startedAfter

integer

startedBefore

integer

expand

string

Responses

Returned if the request is successful

application/json

PageOfWorklogs

Paginated list of worklog details

GET/rest/api/2/issue/{issueIdOrKey}/worklog

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/2/issue/{issueIdOrKey}/worklog`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "maxResults": 1,
  "startAt": 0,
  "total": 1,
  "worklogs": [
    {
      "author": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
      },
      "comment": "I did some work here.",
      "id": "100028",
      "issueId": "10002",
      "self": "https://your-domain.atlassian.net/rest/api/2/issue/10010/worklog/10000",
      "started": "2021-01-17T12:34:00.000+0000",
      "timeSpent": "3h 20m",
      "timeSpentSeconds": 12000,
      "updateAuthor": {
        "accountId": "5b10a2844c20165700ede21g",
        "active": false,
        "displayName": "Mia Krystof",
        "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
      },
      "updated": "2021-01-18T23:45:00.000+0000",
      "visibility": {
        "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
        "type": "group",
        "value": "jira-developers"
      }
    }
  ]
}

POST

Add worklog

Adds a worklog to an issue.

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

This operation can be accessed anonymously.

Permissions required:

Browse projects and Work on issues project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:write:issue-worklog:jira, write:issue-worklog.property:jira, read:avatar:jira, read:group:jira, read:issue-worklog:jira ...(Show more)

Request

Path parameters

issueIdOrKey

string

Required

Query parameters

notifyUsers

boolean

adjustEstimate

string

newEstimate

string

reduceBy

string

expand

string

overrideEditableFlag

boolean

Request bodyapplication/json

comment

string

properties

array<EntityProperty>

started

string

timeSpent

string

timeSpentSeconds

integer

visibility

Visibility

Additional Properties

any

Responses

Returned if the request is successful.

application/json

Worklog

Details of a worklog.

POST/rest/api/2/issue/{issueIdOrKey}/worklog

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "comment": "I did some work here.",
  "started": "2021-01-17T12:34:00.000+0000",
  "timeSpentSeconds": 12000,
  "visibility": {
    "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
    "type": "group"
  }
}`;

const response = await api.asUser().requestJira(route`/rest/api/2/issue/{issueIdOrKey}/worklog`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

201Response

{
  "author": {
    "accountId": "<string>",
    "accountType": "<string>",
    "active": true,
    "avatarUrls": {
      "16x16": "<string>",
      "24x24": "<string>",
      "32x32": "<string>",
      "48x48": "<string>"
    },
    "displayName": "<string>",
    "emailAddress": "<string>",
    "key": "<string>",
    "name": "<string>",
    "self": "<string>",
    "timeZone": "<string>"
  },
  "comment": "<string>",
  "created": "<string>",
  "id": "<string>",
  "issueId": "<string>",
  "properties": [
    {
      "key": "<string>"
    }
  ],
  "self": "<string>",
  "started": "<string>",
  "timeSpent": "<string>",
  "timeSpentSeconds": 192,
  "updateAuthor": {
    "accountId": "<string>",
    "accountType": "<string>",
    "active": true,
    "avatarUrls": {
      "16x16": "<string>",
      "24x24": "<string>",
      "32x32": "<string>",
      "48x48": "<string>"
    },
    "displayName": "<string>",
    "emailAddress": "<string>",
    "key": "<string>",
    "name": "<string>",
    "self": "<string>",
    "timeZone": "<string>"
  },
  "updated": "<string>",
  "visibility": {
    "identifier": "<string>",
    "type": "group",
    "value": "<string>"
  }
}

GET

Get worklog

Returns a worklog.

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

This operation can be accessed anonymously.

Permissions required:

Browse projects project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.
If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:comment:jira, read:group:jira, read:issue-worklog:jira, read:issue-worklog.property:jira, read:project-role:jira ...(Show more)

Request

Path parameters

issueIdOrKey

string

Required

string

Required

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

Worklog

Details of a worklog.

GET/rest/api/2/issue/{issueIdOrKey}/worklog/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/2/issue/{issueIdOrKey}/worklog/{id}`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "author": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
  },
  "comment": "I did some work here.",
  "id": "100028",
  "issueId": "10002",
  "self": "https://your-domain.atlassian.net/rest/api/2/issue/10010/worklog/10000",
  "started": "2021-01-17T12:34:00.000+0000",
  "timeSpent": "3h 20m",
  "timeSpentSeconds": 12000,
  "updateAuthor": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
  },
  "updated": "2021-01-18T23:45:00.000+0000",
  "visibility": {
    "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
    "type": "group",
    "value": "jira-developers"
  }
}

PUT

Update worklog

Updates a worklog.

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

This operation can be accessed anonymously.

Permissions required:

Browse projects project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.
Edit all worklogs project permission to update any worklog or Edit own worklogs to update worklogs created by the user.
If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: WRITE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:read:comment:jira, read:group:jira, read:issue-worklog:jira, read:issue-worklog.property:jira, read:project-role:jira ...(Show more)

Request

Path parameters

issueIdOrKey

string

Required

string

Required

Query parameters

notifyUsers

boolean

adjustEstimate

string

newEstimate

string

expand

string

overrideEditableFlag

boolean

Request bodyapplication/json

comment

string

properties

array<EntityProperty>

started

string

timeSpent

string

timeSpentSeconds

integer

visibility

Visibility

Additional Properties

any

Responses

Returned if the request is successful

application/json

Worklog

Details of a worklog.

PUT/rest/api/2/issue/{issueIdOrKey}/worklog/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "comment": "I did some work here.",
  "started": "2021-01-17T12:34:00.000+0000",
  "timeSpentSeconds": 12000,
  "visibility": {
    "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
    "type": "group"
  }
}`;

const response = await api.asUser().requestJira(route`/rest/api/2/issue/{issueIdOrKey}/worklog/{id}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "author": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
  },
  "comment": "I did some work here.",
  "id": "100028",
  "issueId": "10002",
  "self": "https://your-domain.atlassian.net/rest/api/2/issue/10010/worklog/10000",
  "started": "2021-01-17T12:34:00.000+0000",
  "timeSpent": "3h 20m",
  "timeSpentSeconds": 12000,
  "updateAuthor": {
    "accountId": "5b10a2844c20165700ede21g",
    "active": false,
    "displayName": "Mia Krystof",
    "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
  },
  "updated": "2021-01-18T23:45:00.000+0000",
  "visibility": {
    "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
    "type": "group",
    "value": "jira-developers"
  }
}

DEL

Delete worklog

Deletes a worklog from an issue.

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

This operation can be accessed anonymously.

Permissions required:

Browse projects project permission for the project that the issue is in.
If issue-level security is configured, issue-level security permission to view the issue.
Delete all worklogs project permission to delete any worklog or Delete own worklogs to delete worklogs created by the user,
If the worklog has visibility restrictions, belongs to the group or has the role visibility is restricted to.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: DELETE

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:jira-work

Granular:delete:issue-worklog:jira, delete:issue-worklog.property:jira, write:issue.time-tracking:jira

Request

Path parameters

issueIdOrKey

string

Required

string

Required

Query parameters

notifyUsers

boolean

adjustEstimate

string

newEstimate

string

increaseBy

string

overrideEditableFlag

boolean

Responses

Returned if the request is successful.

DEL/rest/api/2/issue/{issueIdOrKey}/worklog/{id}

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/2/issue/{issueIdOrKey}/worklog/{id}`, {
  method: 'DELETE'
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());

GET

Get IDs of deleted worklogs

Returns a list of IDs and delete timestamps for worklogs deleted after a date and time.

This resource is paginated, with a limit of 1000 worklogs per page. Each page lists worklogs from oldest to youngest. If the number of items in the date range exceeds 1000, until indicates the timestamp of the youngest item on the page. Also, nextPage provides the URL for the next page of worklogs. The lastPage parameter is set to true on the last page of worklogs.

This resource does not return worklogs deleted during the minute preceding the request.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:issue-worklog:jira, read:issue-worklog.property:jira

Request

Query parameters

since

integer

Responses

Returned if the request is successful.

application/json

ChangedWorklogs

List of changed worklogs.

GET/rest/api/2/worklog/deleted

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/2/worklog/deleted`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "lastPage": true,
  "nextPage": "https://your-domain.atlassian.net/api/~ver~/worklog/deleted?since=1438013693136",
  "self": "https://your-domain.atlassian.net/api/~ver~/worklog/deleted?since=1438013671562",
  "since": 1438013671562,
  "until": 1438013693136,
  "values": [
    {
      "properties": [],
      "updatedTime": 1438013671562,
      "worklogId": 103
    },
    {
      "properties": [],
      "updatedTime": 1438013672165,
      "worklogId": 104
    },
    {
      "properties": [],
      "updatedTime": 1438013693136,
      "worklogId": 105
    }
  ]
}

POST

Get worklogs

Returns worklog details for a list of worklog IDs.

The returned list of worklogs is limited to 1000 items.

Permissions required: Permission to access Jira, however, worklogs are only returned where either of the following is true:

the worklog is set as Viewable by All Users.
the user is a member of a project role or group with permission to view the worklog.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:comment:jira, read:group:jira, read:issue-worklog:jira, read:issue-worklog.property:jira, read:project-role:jira ...(Show more)

Request

Query parameters

expand

string

Request bodyapplication/json

A JSON object containing a list of worklog IDs.

ids

array<integer>

Required

Responses

Returned if the request is successful.

application/json

array<Worklog>

POST/rest/api/2/worklog/list

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

var bodyData = `{
  "ids": [
    1,
    2,
    5,
    10
  ]
}`;

const response = await api.asUser().requestJira(route`/rest/api/2/worklog/list`, {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

[
  {
    "author": {
      "accountId": "5b10a2844c20165700ede21g",
      "active": false,
      "displayName": "Mia Krystof",
      "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
    },
    "comment": "I did some work here.",
    "id": "100028",
    "issueId": "10002",
    "self": "https://your-domain.atlassian.net/rest/api/2/issue/10010/worklog/10000",
    "started": "2021-01-17T12:34:00.000+0000",
    "timeSpent": "3h 20m",
    "timeSpentSeconds": 12000,
    "updateAuthor": {
      "accountId": "5b10a2844c20165700ede21g",
      "active": false,
      "displayName": "Mia Krystof",
      "self": "https://your-domain.atlassian.net/rest/api/2/user?accountId=5b10a2844c20165700ede21g"
    },
    "updated": "2021-01-18T23:45:00.000+0000",
    "visibility": {
      "identifier": "276f955c-63d7-42c8-9520-92d01dca0625",
      "type": "group",
      "value": "jira-developers"
    }
  }
]

GET

Get IDs of updated worklogs

Returns a list of IDs and update timestamps for worklogs updated after a date and time.

This resource does not return worklogs updated during the minute preceding the request.

Permissions required: Permission to access Jira, however, worklogs are only returned where either of the following is true:

the worklog is set as Viewable by All Users.
the user is a member of a project role or group with permission to view the worklog.

Data Security Policy: Not exempt from app access rules

Scopes

Connect app scope required: READ

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:issue-worklog:jira, read:issue-worklog.property:jira

Request

Query parameters

since

integer

expand

string

Responses

Returned if the request is successful.

application/json

ChangedWorklogs

List of changed worklogs.

GET/rest/api/2/worklog/updated

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";

const response = await api.asUser().requestJira(route`/rest/api/2/worklog/updated`, {
  headers: {
    'Accept': 'application/json'
  }
});

console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());

200Response

{
  "lastPage": true,
  "nextPage": "https://your-domain.atlassian.net/api/~ver~/worklog/updated?since=1438013693136",
  "self": "https://your-domain.atlassian.net/api/~ver~/worklog/updated?since=1438013671562",
  "since": 1438013671562,
  "until": 1438013693136,
  "values": [
    {
      "properties": [],
      "updatedTime": 1438013671562,
      "worklogId": 103
    },
    {
      "properties": [],
      "updatedTime": 1438013672165,
      "worklogId": 104
    },
    {
      "properties": [],
      "updatedTime": 1438013693136,
      "worklogId": 105
    }
  ]
}