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.
Connect app scope required: READ
read:jira-workread:field:jira, read:avatar:jira, read:project-category:jira, read:project:jira, read:field-configuration:jiraThis 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.
Connect app scope required: ADMIN
manage:jira-configurationwrite:field:jira, read:avatar:jira, read:field:jira, read:project-category:jira, read:project:jira ...(Show more)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:
idqueryid and queryOnly custom fields can be queried, type must be set to custom.
Permissions required: Administer Jira global permission.
Connect app scope required: NONE
read:jira-workread:field:jira, read:field-configuration:jirainteger
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
{
"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",
"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",
"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.
Connect app scope required: READ
read:jira-workread:field:jira, read:field-configuration:jira, read:user:jirainteger
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.
Connect app scope required: ADMIN
manage:jira-configurationwrite:field:jirastring
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.
Connect app scope required: NONE
manage:jira-projectread:field:jira, read:avatar:jira, read:project-category:jira, read:project:jirastring
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.
Connect app scope required: ADMIN
manage:jira-configurationdelete:field:jirastring
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.
Connect app scope required: ADMIN
manage:jira-configurationwrite:field:jirastring
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.
Connect app scope required: ADMIN
manage:jira-configurationdelete:field:jirastring
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: