This resource represents issue fields, both system and custom fields. Use it to get fields, field configurations, and create custom fields.
Returns system and custom issue fields according to the following rules:
This operation can be accessed anonymously.
Permissions required: None.
read:jira-work
read:field:jira
, read:avatar:jira
, read:project-category:jira
, read:project:jira
, read:field-configuration:jira
Connect app scope required: READ
This request has no parameters.
Returned if the request is successful.
array<FieldDetails>
1
2
3
4
5
6
7
8
9
10
11
12
// 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/field`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
[
{
"clauseNames": [
"description"
],
"custom": false,
"id": "description",
"name": "Description",
"navigable": true,
"orderable": true,
"schema": {
"system": "description",
"type": "string"
},
"searchable": true
},
{
"clauseNames": [
"summary"
],
"custom": false,
"id": "summary",
"key": "summary",
"name": "Summary",
"navigable": true,
"orderable": true,
"schema": {
"system": "summary",
"type": "string"
},
"searchable": true
}
]
Creates a custom field.
Permissions required: Administer Jira global permission.
manage:jira-configuration
write:field:jira
, read:avatar:jira
, read:field:jira
, read:project-category:jira
, read:project:jira
...(Show more)Connect app scope required: ADMIN
Definition of the custom field to be created
string
string
Requiredstring
string
RequiredReturned if the custom field is created.
Details about a field.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"description": "Custom field for picking groups",
"name": "New custom field",
"searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:grouppickersearcher",
"type": "com.atlassian.jira.plugin.system.customfieldtypes:grouppicker"
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/field`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
"clauseNames": [
"cf[10101]",
"New custom field"
],
"custom": true,
"id": "customfield_10101",
"key": "customfield_10101",
"name": "New custom field",
"navigable": true,
"orderable": true,
"schema": {
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:project",
"customId": 10101,
"type": "project"
},
"searchable": true,
"untranslatedName": "New custom field"
}
Returns a paginated list of fields for Classic Jira projects. The list can include:
id
query
id
and query
Use type
must be set to custom
to show custom fields only.
Permissions required: Administer Jira global permission.
read:jira-work
read:field:jira
, read:field-configuration:jira
Connect app scope required: NONE
integer
integer
array<string>
array<string>
string
string
string
Returned if the request is successful.
A page of items.
1
2
3
4
5
6
7
8
9
10
11
12
// 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/field/search`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
"isLast": false,
"maxResults": 50,
"startAt": 0,
"total": 2,
"values": [
{
"id": "customfield_10000",
"name": "Approvers",
"schema": {
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker",
"customId": 10000,
"items": "user",
"type": "array"
},
"description": "Contains users needed for approval. This custom field was created by Jira Service Desk.",
"key": "customfield_10000",
"stableId": "sfid:approvers",
"isLocked": true,
"searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:userpickergroupsearcher",
"screensCount": 2,
"contextsCount": 2,
"lastUsed": {
"type": "TRACKED",
"value": "2021-01-28T07:37:40.000+0000"
}
},
{
"id": "customfield_10001",
"name": "Change reason",
"schema": {
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:select",
"customId": 10001,
"type": "option"
},
"description": "Choose the reason for the change request",
"key": "customfield_10001",
"stableId": "sfid:change-reason",
"isLocked": false,
"searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:multiselectsearcher",
"screensCount": 2,
"contextsCount": 2,
"projectsCount": 2,
"lastUsed": {
"type": "NOT_TRACKED"
}
}
]
}
Returns a paginated list of fields in the trash. The list may be restricted to fields whose field name or description partially match a string.
Only custom fields can be queried, type
must be set to custom
.
Permissions required: Administer Jira global permission.
read:jira-work
read:field:jira
, read:field-configuration:jira
, read:user:jira
Connect app scope required: READ
integer
integer
array<string>
string
string
string
Returned if the request is successful.
A page of items.
1
2
3
4
5
6
7
8
9
10
11
12
// 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/field/search/trashed`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
"isLast": false,
"maxResults": 50,
"startAt": 0,
"total": 1,
"values": [
{
"id": "customfield_10000",
"name": "Approvers",
"schema": {
"custom": "com.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker",
"customId": 10003,
"type": "array"
},
"description": "Contains users needed for approval. This custom field was created by Jira Service Desk.",
"key": "customfield_10003",
"trashedDate": "2022-10-06T07:32:47.000+0000",
"trashedBy": {
"accountId": "5b10a2844c20165700ede21g",
"active": true,
"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",
"self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
"timeZone": "Australia/Sydney"
},
"plannedDeletionDate": "2022-10-24T07:32:47.000+0000"
}
]
}
Updates a custom field.
Permissions required: Administer Jira global permission.
manage:jira-configuration
write:field:jira
Connect app scope required: ADMIN
string
RequiredThe custom field update details.
string
string
string
Returned if the request is successful.
any
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"description": "Select the manager and the corresponding employee.",
"name": "Managers and employees list",
"searcherKey": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearcher"
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/field/{fieldId}`, {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
Returns a paginated list of the contexts a field is used in. Deprecated, use Get custom field contexts.
Permissions required: Administer Jira global permission.
manage:jira-project
read:field:jira
, read:avatar:jira
, read:project-category:jira
, read:project:jira
Connect app scope required: NONE
string
Requiredinteger
integer
Returned if the request is successful.
A page of items.
1
2
3
4
5
6
7
8
9
10
11
12
// 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/field/{fieldId}/contexts`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
1
2
3
4
5
6
7
8
9
10
11
12
{
"isLast": false,
"maxResults": 1,
"startAt": 0,
"total": 5,
"values": [
{
"id": 10001,
"name": "Default Context"
}
]
}
Deletes a custom field. The custom field is deleted whether it is in the trash or not. See Edit or delete a custom field for more information on trashing and deleting custom fields.
This operation is asynchronous. Follow the location
link in the response to determine the status of the task and use Get task to obtain subsequent updates.
Permissions required: Administer Jira global permission.
manage:jira-configuration
delete:field:jira
Connect app scope required: ADMIN
string
RequiredReturned if the request is successful.
Details about a task.
1
2
3
4
5
6
7
8
9
10
// 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/field/{id}`, {
method: 'DELETE'
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"description": "<string>",
"elapsedRuntime": 48,
"finished": 49,
"id": "<string>",
"lastUpdate": 62,
"message": "<string>",
"progress": 51,
"self": "<string>",
"started": 48,
"status": "ENQUEUED",
"submitted": 50,
"submittedBy": 42
}
Restores a custom field from trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.
Permissions required: Administer Jira global permission.
manage:jira-configuration
write:field:jira
Connect app scope required: ADMIN
string
RequiredReturned if the request is successful.
any
1
2
3
4
5
6
7
8
9
10
11
12
13
// 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/field/{id}/restore`, {
method: 'POST',
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
Moves a custom field to trash. See Edit or delete a custom field for more information on trashing and deleting custom fields.
Permissions required: Administer Jira global permission.
manage:jira-configuration
delete:field:jira
Connect app scope required: ADMIN
string
RequiredReturned if the request is successful.
any
1
2
3
4
5
6
7
8
9
10
11
12
13
// 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/field/{id}/trash`, {
method: 'POST',
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());
Rate this page: