Cloud

Jira Cloud platform / Reference / REST API v3

Myself

This resource represents information about the current user, such as basic details, group membership, application roles, preferences, and locale. Use it to get, create, update, and delete (restore default) values of the user's preferences and locale.

Operations

GET/rest/api/3/mypreferences PUT/rest/api/3/mypreferences DEL/rest/api/3/mypreferences GET/rest/api/3/mypreferences/locale PUT/rest/api/3/mypreferences/locale DEL/rest/api/3/mypreferences/locale GET/rest/api/3/myself

GET

Get preference

Returns the value of a preference of the current user.

Note that these keys are deprecated:

jira.user.locale The locale of the user. By default this is not set and the user takes the locale of the instance.
jira.user.timezone The time zone of the user. By default this is not set and the user takes the timezone of the instance.

These system preferences keys will be deprecated by 15/07/2024. You can still retrieve these keys, but it will not have any impact on Notification behaviour.

user.notifications.watcher Whether the user gets notified when they are watcher.
user.notifications.assignee Whether the user gets notified when they are assignee.
user.notifications.reporter Whether the user gets notified when they are reporter.
user.notifications.mentions Whether the user gets notified when they are mentions.

Use Update a user profile from the user management REST API to manage timezone and locale instead.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user-configuration:jira

Connect app scope required: ACT_AS_USER

Request

Query parameters

key

string

Required

Responses

Returned if the request is successful.

application/json

string

GET/rest/api/3/mypreferences

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/3/mypreferences?key={key}`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

"<string>"

PUT

Set preference

Creates a preference for the user or updates a preference's value by sending a plain text string. For example, false. An arbitrary preference can be created with the value containing up to 255 characters. In addition, the following keys define system preferences that can be set or created:

user.notifications.mimetype The mime type used in notifications sent to the user. Defaults to html.
user.default.share.private Whether new filters are set to private. Defaults to true.
user.keyboard.shortcuts.disabled Whether keyboard shortcuts are disabled. Defaults to false.
user.autowatch.disabled Whether the user automatically watches issues they create or add a comment to. By default, not set: the user takes the instance autowatch setting.
user.notifiy.own.changes Whether the user gets notified of their own changes.

Note that these keys are deprecated:

jira.user.locale The locale of the user. By default, not set. The user takes the instance locale.
jira.user.timezone The time zone of the user. By default, not set. The user takes the instance timezone.

These system preferences keys will be deprecated by 15/07/2024. You can still use these keys to create arbitrary preferences, but it will not have any impact on Notification behaviour.

user.notifications.watcher Whether the user gets notified when they are watcher.
user.notifications.assignee Whether the user gets notified when they are assignee.
user.notifications.reporter Whether the user gets notified when they are reporter.
user.notifications.mentions Whether the user gets notified when they are mentions.

Use Update a user profile from the user management REST API to manage timezone and locale instead.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:write:user-configuration:jira

Connect app scope required: ACT_AS_USER

Request

Query parameters

key

string

Required

Request bodyapplication/json text/plain

The value of the preference as a plain text string. The maximum length is 255 characters.

string

Responses

Returned if the request is successful.

application/json

any

PUT/rest/api/3/mypreferences

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 = `"<string>"`;

const response = await api.asUser().requestJira(route`/rest/api/3/mypreferences?key={key}`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

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

DEL

Delete preference

Deletes a preference of the user, which restores the default value of system defined settings.

Note that these keys are deprecated:

jira.user.locale The locale of the user. By default, not set. The user takes the instance locale.
jira.user.timezone The time zone of the user. By default, not set. The user takes the instance timezone.

Use Update a user profile from the user management REST API to manage timezone and locale instead.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:delete:user-configuration:jira

Connect app scope required: ACT_AS_USER

Request

Query parameters

key

string

Required

Responses

Returned if the request is successful.

DEL/rest/api/3/mypreferences

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/3/mypreferences?key={key}`, {
  method: 'DELETE'
});

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

GET

Get locale

Returns the locale for the user.

If the user has no language preference set (which is the default setting) or this resource is accessed anonymous, the browser locale detected by Jira is returned. Jira detects the browser locale using the Accept-Language header in the request. However, if this doesn't match a locale available Jira, the site default locale is returned.

This operation can be accessed anonymously.

Permissions required: None.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-configuration

Granular:read:user-configuration:jira

Connect app scope required: ACT_AS_USER

Request

This request has no parameters.

Responses

Returned if the request is successful.

application/json

Locale

Details of a locale.

GET/rest/api/3/mypreferences/locale

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/3/mypreferences/locale`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

1
2
3

{
  "locale": "en_US"
}

PUT

Set localeDeprecated

Deprecated, use Update a user profile from the user management REST API instead.

Sets the locale of the user. The locale must be one supported by the instance of Jira.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

Connect apps cannot access this REST resource.

Request

Request bodyapplication/json

The locale defined in a LocaleBean.

locale

string

Responses

Returned if the request is successful.

application/json

any

PUT/rest/api/3/mypreferences/locale

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

var bodyData = `{
  "locale": "en_US"
}`;

const response = await api.requestJira(route`/rest/api/3/mypreferences/locale`, {
  method: 'PUT',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: bodyData
});

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

DEL

Delete localeDeprecated

Deprecated, use Update a user profile from the user management REST API instead.

Deletes the locale of the user, which restores the default setting.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

Connect apps cannot access this REST resource.

Request

This request has no parameters.

Responses

Returned if the request is successful.

application/json

any

DEL/rest/api/3/mypreferences/locale

Forge

curl

Node.js

Java

Python

PHP

// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
//
// This API resource doesn't support Oauth2 (3LO). See alternate authorization methods:
// https://developer.atlassian.com/cloud/jira/platform/rest/v3/#authentication
import api, { route } from "@forge/api";

const response = await api.requestJira(route`/rest/api/3/mypreferences/locale`, {
  method: 'DELETE',
  headers: {
    'Accept': 'application/json'
  }
});

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

GET

Get current user

Returns details for the current user.

Permissions required: Permission to access Jira.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-user

Granular:read:application-role:jira, read:group:jira, read:user:jira, read:avatar:jira

Connect app scope required: READ

Request

Query parameters

expand

string

Responses

Returned if the request is successful.

application/json

User

A user with details as permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions:

User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, displayName provides an indication and other parameters have default values or are blank (for example, email is blank).
User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, accountId returns unknown and all other parameters have fallback values.
User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values.

GET/rest/api/3/myself

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/3/myself`, {
  headers: {
    'Accept': 'application/json'
  }
});

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

200Response

{
  "accountId": "5b10a2844c20165700ede21g",
  "accountType": "atlassian",
  "active": true,
  "applicationRoles": {
    "items": [],
    "size": 1
  },
  "avatarUrls": {
    "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
    "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
    "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32",
    "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48"
  },
  "displayName": "Mia Krystof",
  "emailAddress": "mia@example.com",
  "groups": {
    "items": [],
    "size": 3
  },
  "key": "",
  "name": "",
  "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
  "timeZone": "Australia/Sydney"
}