Atlassian Jira Field API
The Atlassian Jira Field API enables managing custom and system fields within Jira including contexts, options, and configurations.
OpenAPI Specification
components:
schemas:
PageBeanField:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Field'
readOnly: true
type: array
type: object
PageBeanCustomFieldContext:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/CustomFieldContext'
readOnly: true
type: array
type: object
PageBeanCustomFieldContextDefaultValue:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/CustomFieldContextDefaultValue'
readOnly: true
type: array
type: object
PageBeanIssueTypeToContextMapping:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/IssueTypeToContextMapping'
readOnly: true
type: array
type: object
PageBeanContextForProjectAndIssueType:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/ContextForProjectAndIssueType'
readOnly: true
type: array
type: object
PageBeanCustomFieldContextProjectMapping:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/CustomFieldContextProjectMapping'
readOnly: true
type: array
type: object
PageBeanCustomFieldContextOption:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/CustomFieldContextOption'
readOnly: true
type: array
type: object
CustomFieldCreatedContextOptionsList:
additionalProperties: false
description: A list of custom field options for a context.
properties:
options:
description: The created custom field options.
items:
$ref: '#/components/schemas/CustomFieldContextOption'
type: array
type: object
CustomFieldUpdatedContextOptionsList:
additionalProperties: false
description: A list of custom field options for a context.
properties:
options:
description: The updated custom field options.
items:
$ref: '#/components/schemas/CustomFieldOptionUpdate'
type: array
type: object
PageBeanContext:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Context'
readOnly: true
type: array
type: object
PageBeanScreenWithTab:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/ScreenWithTab'
readOnly: true
type: array
type: object
PageBeanIssueFieldOption:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/IssueFieldOption'
readOnly: true
type: array
type: object
IssueFieldOption:
additionalProperties: false
description: Details of the options for a select list issue field.
properties:
config:
$ref: '#/components/schemas/IssueFieldOptionConfiguration'
id:
description: >-
The unique identifier for the option. This is only unique within the
select field's set of options.
format: int64
type: integer
properties:
additionalProperties: {}
description: >-
The properties of the object, as arbitrary key-value pairs. These
properties can be searched using JQL, if the extractions (see [Issue
Field Option Property
Index](https://developer.atlassian.com/cloud/jira/platform/modules/issue-field-option-property-index/))
are defined in the descriptor for the issue field module.
type: object
value:
description: The option's name, which is displayed in Jira.
type: string
required:
- id
- value
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/field/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/field/search:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of fields for Classic Jira
projects. The list can include:<br><br> * all fields<br> * specific
fields, by defining `id`<br> * fields that contain a string in the
field name or description, by defining `query`<br> * specific fields
that contain a string in the field name or description, by defining `id`
and `query`<br><br>Only custom fields can be queried, `type` must be set
to `custom`.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetfieldspaginated
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- description: The type of fields to search.
in: query
name: type
schema:
items:
default: ''
enum:
- custom
- system
type: string
type: array
- description: >-
The IDs of the custom fields to return or, where `query` is
specified, filter.
in: query
name: id
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
- description: >-
String used to perform a case-insensitive partial match with field
names or descriptions.
in: query
name: query
schema:
type: string
- description: |-
[Order](#ordering) the results by a field:
* `contextsCount` sorts by the number of contexts related to a field
* `lastUsed` sorts by the date when the value of the field last changed
* `name` sorts by the field name
* `screensCount` sorts by the number of screens related to a field
in: query
name: orderBy
schema:
enum:
- contextsCount
- '-contextsCount'
- +contextsCount
- lastUsed
- '-lastUsed'
- +lastUsed
- name
- '-name'
- +name
- screensCount
- '-screensCount'
- +screensCount
- projectsCount
- '-projectsCount'
- +projectsCount
type: string
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expand
options include:
* `key` returns the key for each field
* `lastUsed` returns the date when the value of the field last changed
* `screensCount` returns the number of screens related to a field
* `contextsCount` returns the number of contexts related to a field
* `isLocked` returns information about whether the field is [locked](https://confluence.atlassian.com/x/ZSN7Og)
* `searcherKey` returns the searcher key for each custom field
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"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"}}]}
schema:
$ref: '#/components/schemas/PageBeanField'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Only custom fields can be
queried."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access
fields."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Get Fields Paginated
tags:
- Issue Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:field:jira
- read:field-configuration:jira
state: Beta
x-atlassian-connect-scope: NONE
/rest/api/3/field/search/trashed:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of fields in the trash. The list
may be restricted to fields whose field name or description partially
match a string.<br><br>Only custom fields can be queried, `type` must be
set to `custom`.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGettrashedfieldspaginated
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- in: query
name: id
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
- description: >-
String used to perform a case-insensitive partial match with field
names or descriptions.
in: query
name: query
schema:
type: string
- in: query
name: expand
schema:
enum:
- name
- '-name'
- +name
- trashDate
- '-trashDate'
- +trashDate
- plannedDeletionDate
- '-plannedDeletionDate'
- +plannedDeletionDate
- projectsCount
- '-projectsCount'
- +projectsCount
type: string
- description: |-
[Order](#ordering) the results by a field:
* `name` sorts by the field name
* `trashDate` sorts by the date the field was moved to the trash
* `plannedDeletionDate` sorts by the planned deletion date
in: query
name: orderBy
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"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":"[email protected]","self":"https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g","timeZone":"Australia/Sydney"},"plannedDeletionDate":"2022-10-24T07:32:47.000+0000"}]}
schema:
$ref: '#/components/schemas/PageBeanField'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Only custom fields can be
queried."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access
fields."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
summary: Atlassian Get Fields In Trash Paginated
tags:
- Issue Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:field:jira
- read:field-configuration:jira
- read:user:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/field/{fieldId}:
put:
deprecated: false
description: >-
Updates a custom field.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdatecustomfield
parameters:
- description: The ID of the custom field.
in: path
name: fieldId
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
description: Select the manager and the corresponding employee.
name: Managers and employees list
searcherKey: >-
com.atlassian.jira.plugin.system.customfieldtypes:cascadingselectsearcher
schema:
$ref: '#/components/schemas/UpdateCustomFieldDetails'
description: The custom field update details.
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["searcherKey is invalid for the field
type."],"errors":{}}
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can edit custom
fields."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
description: Returned if the custom field is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Update Custom Field
tags:
- Issue Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-configuration
state: Current
- scheme: OAuth2
scopes:
- write:field:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/field/{fieldId}/context:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of [
contexts](https://confluence.atlassian.com/adminjiracloud/what-are-custom-field-contexts-991923859.html)
for a custom field. Contexts can be returned as follows:<br><br> * With
no other parameters set, all contexts.<br> * By defining `id` only, all
contexts from the list of IDs.<br> * By defining `isAnyIssueType`,
limit the list of contexts returned to either those that apply to all
issue types (true) or those that apply to only a subset of issue types
(false)<br> * By defining `isGlobalContext`, limit the list of contexts
return to either those that apply to all projects (global contexts)
(true) or those that apply to only a subset of projects
(false).<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetcontextsforfield
parameters:
- description: The ID of the custom field.
in: path
name: fieldId
required: true
schema:
type: string
- description: Whether to return contexts that apply to all issue types.
in: query
name: isAnyIssueType
schema:
type: boolean
- description: Whether to return contexts that apply to all projects.
in: query
name: isGlobalContext
schema:
type: boolean
- description: >-
The list of context IDs. To include multiple contexts, separate IDs
with ampersand: `contextId=10000&contextId=10001`.
in: query
name: contextId
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":100,"startAt":0,"total":2,"values":[{"id":"10025","name":"Bug
fields context","description":"A context used to define the
custom field options for
bugs.","isGlobalContext":true,"isAnyIssueType":false},{"id":"10026","name":"Task
fields context","description":"A context used to define the
custom field options for
tasks.","isGlobalContext":false,"isAnyIssueType":false}]}
schema:
$ref: '#/components/schemas/PageBeanCustomFieldContext'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access custom
field contexts."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The custom field was not
found."],"errors":{}}
description: Returned if the custom field was not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Custom Field Contexts
tags:
- Issue Custom Field Contexts
# --- truncated at 32 KB (151 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-field--openapi-original.yml