Atlassian Jira Field Configuration Scheme API
The Atlassian Jira Field Configuration Scheme API enables defining how custom fields appear across different issue screens.
OpenAPI Specification
components:
schemas:
PageBeanFieldConfigurationIssueTypeItem:
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/FieldConfigurationIssueTypeItem'
readOnly: true
type: array
type: object
PageBeanFieldConfigurationSchemeProjects:
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/FieldConfigurationSchemeProjects'
readOnly: true
type: array
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/fieldconfigurationscheme/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/fieldconfigurationscheme/mapping:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of field configuration issue
type items.<br><br>Only items used in classic projects are
returned.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetfieldconfigurationschememappings
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 list of field configuration scheme IDs. To include multiple
field configuration schemes separate IDs with ampersand:
`fieldConfigurationSchemeId=10000&fieldConfigurationSchemeId=10001`.
in: query
name: fieldConfigurationSchemeId
schema:
items:
example: 10020
format: int64
type: integer
maxItems: 50
minItems: 1
type: array
uniqueItems: true
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":100,"startAt":0,"total":5,"values":[{"fieldConfigurationSchemeId":"10020","issueTypeId":"10000","fieldConfigurationId":"10010"},{"fieldConfigurationSchemeId":"10020","issueTypeId":"10001","fieldConfigurationId":"10010"},{"fieldConfigurationSchemeId":"10021","issueTypeId":"10002","fieldConfigurationId":"10000"},{"fieldConfigurationSchemeId":"10022","issueTypeId":"default","fieldConfigurationId":"10011"},{"fieldConfigurationSchemeId":"10023","issueTypeId":"default","fieldConfigurationId":"10000"}]}
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationIssueTypeItem'
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if no field configuration schemes are found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Field Configuration Issue Type Items
tags:
- Issue Field Configurations
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:
- read:field-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme/project:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of field configuration schemes
and, for each scheme, a list of the projects that use it.<br><br>The
list is sorted by field configuration scheme ID. The first item contains
the list of project IDs assigned to the default field configuration
scheme.<br><br>Only field configuration schemes used in classic projects
are returned.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetfieldconfigurationschemeprojectmapping
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 list of project IDs. To include multiple projects, separate IDs
with ampersand: `projectId=10000&projectId=10001`.
in: query
name: projectId
required: true
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":50,"startAt":0,"total":5,"values":[{"projectIds":["10","11"]},{"fieldConfigurationScheme":{"id":"10002","name":"Field
Configuration Scheme for software related
projects","description":"We can use this one for software
projects."},"projectIds":["12","13","14"]}]}
schema:
$ref: '#/components/schemas/PageBeanFieldConfigurationSchemeProjects'
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Field Configuration Schemes For Projects
tags:
- Issue Field Configurations
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:
- read:field-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Assigns a field configuration scheme to a project. If the field
configuration scheme ID is `null`, the operation assigns the default
field configuration scheme.<br><br>Field configuration schemes can only
be assigned to classic projects.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAssignfieldconfigurationschemetoproject
parameters: []
requestBody:
content:
application/json:
example:
fieldConfigurationSchemeId: '10000'
projectId: '10000'
schema:
$ref: '#/components/schemas/FieldConfigurationSchemeProjectAssociation'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Only classic projects can have field
configuration schemes assigned."],"errors":{}}
description: Returned if the project is not a classic project.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access field
configurations."],"errors":{}}
description: Returned if the user does not have the necessary permissions.
'404':
content:
application/json:
example: '{"errorMessages":["The project was not found."],"errors":{}}'
description: Returned if the project is missing.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Assign Field Configuration Scheme To Project
tags:
- Issue Field Configurations
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-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme/{id}:
delete:
deprecated: false
description: >-
Deletes a field configuration scheme.<br><br>This operation can only
delete field configuration schemes used in company-managed (classic)
projects.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeletefieldconfigurationscheme
parameters:
- description: The ID of the field configuration scheme.
in: path
name: id
required: true
schema:
format: int64
type: integer
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: Returned if the field configuration scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Field Configuration Scheme
tags:
- Issue Field Configurations
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:
- delete:field-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates a field configuration scheme.<br><br>This operation can only
update field configuration schemes used in company-managed (classic)
projects.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdatefieldconfigurationscheme
parameters:
- description: The ID of the field configuration scheme.
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
description: We can use this one for software projects.
name: Field Configuration Scheme for software related projects
schema:
$ref: '#/components/schemas/UpdateFieldConfigurationSchemeDetails'
description: The details of the field configuration scheme.
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["A field configuration scheme is using this
name."],"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 access field
configurations."],"errors":{}}
description: Returned if the user does not have the necessary permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The field configuration scheme was not
found."],"errors":{}}
description: Returned if the field configuration scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Update Field Configuration Scheme
tags:
- Issue Field Configurations
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-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme/{id}/mapping:
put:
deprecated: false
description: >-
Assigns issue types to field configurations on field configuration
scheme.<br><br>This operation can only modify field configuration
schemes used in company-managed (classic)
projects.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianSetfieldconfigurationschememapping
parameters:
- description: The ID of the field configuration scheme.
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
mappings:
- fieldConfigurationId: '10000'
issueTypeId: default
- fieldConfigurationId: '10002'
issueTypeId: '10001'
- fieldConfigurationId: '10001'
issueTypeId: '10002'
schema:
$ref: >-
#/components/schemas/AssociateFieldConfigurationsWithIssueTypesRequest
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the necessary permission.
'404':
description: >-
Returned if the field configuration scheme, the field configuration,
or the issue type is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Assign Issue Types To Field Configurations
tags:
- Issue Field Configurations
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-configuration-scheme:jira
- read:field-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/fieldconfigurationscheme/{id}/mapping/delete:
post:
deprecated: false
description: >-
Removes issue types from the field configuration scheme.<br><br>This
operation can only modify field configuration schemes used in
company-managed (classic) projects.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianRemoveissuetypesfromglobalfieldconfigurationscheme
parameters:
- description: The ID of the field configuration scheme.
in: path
name: id
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
issueTypeIds:
- '10000'
- '10001'
- '10002'
schema:
$ref: '#/components/schemas/IssueTypeIdsToRemove'
description: The issue type IDs to remove.
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The issueTypeIds must not contain
duplicates."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the request is not valid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access field
configurations."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: Returned if the user does not have the necessary permission.
'404':
content:
application/json:
example: >-
{"errorMessages":["The field configuration scheme was not
found."],"errors":{}}
schema:
$ref: '#/components/schemas/ErrorCollection'
description: >-
Returned if the field configuration scheme or the issue types are
not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Remove Issue Types From Field Configuration Scheme
tags:
- Issue Field Configurations
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-configuration-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Issue Field Configurations
x-atlassian-narrative:
documents:
- anchor: about
body: >-
The Jira REST API enables you to interact with Jira programmatically.
Use this API to
[build
apps](https://developer.atlassian.com/cloud/jira/platform/integrating-with-jira-cloud/),
script interactions with
Jira, or develop any other type of integration. This page documents the
REST resources available in Jira Cloud, including
the HTTP response codes and example requests and responses.
title: About
- anchor: version
body: >
This documentation is for **version 3** of the Jira Cloud platform REST
API, which is the latest version
but is in **beta**. [Version
2](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) and
version 3 of the API offer the same collection of operations. However,
version 3 provides support for
the [Atlassian Document
Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)
(ADF) in:
- `body` in comments, including where comments are used in issue, issue
link, and transition resources.
- `comment` in worklogs.
- `description` and `environment` fields in issues.
- `textarea` type custom fields (multi-line text fields) in issues.
Single line custom fields
(`textfield`) accept a string and don't handle Atlassian Document Format content.
However, these new features are under development and may change.
title: Version
- anchor: authentication
body: >
### Forge apps
For Forge apps, [REST API
scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)
are used when authenticating with Jira Cloud platform. See [Add scopes
to call an Atlassian REST
API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/)
for more details.
The URIs for Forge app REST API calls have this structure:
`/rest/api/3/<resource-name>`
For example, `/rest/api/3/issue/DEMO-1`
### Connect apps
For Connect apps, authentication (JWT-based) is built into the Connect
libraries. Authorization is implemented using either
scopes (shown as _App scope required_ for operations on this page) or
user impersonation. See
[Security for Connect
apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)
for details.
The URIs for Connect app REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
### Other integrations
For integrations that are not Forge or Connect apps, use OAuth 2.0
authorization code grants (3LO) for security
(3LO scopes are shown as for operations _OAuth scopes required_). See
[OAuth 2.0 (3LO)
apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)
for details.
The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:
`https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/<resource-name>`
For example,
`https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/api/3/issue/DEMO-1`
### Ad-hoc API calls
For personal scripts, bots, and ad-hoc execution of the REST APIs use
basic authentication. See [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)
for details.
The URIs for basic authentication REST API calls have this structure:
`https://<site-url>/rest/api/3/<resource-name>`
For example, `https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1`
title: Authentication and authorization
- anchor: permissions
body: >
### Operation permissions
Most operations in this API require permissions. The calling user must
have the required permissions for an operation to
use it. Note that for Connect apps, the app user must have the required
permissions for the operation and the app must
have scopes that permit the operation.
A permission can be granted to a group, project role, or issue role that
the user is a member of, or granted directly to a user.
See [Permissions overview](https://confluence.atlassian.com/x/FQiiLQ)
for details. The most common permissions are:
- **Administer the Cloud site**: Users in the _site-admins_ group have
this
permission. See [Manage
groups](https://confluence.atlassian.com/x/24xjL) for details.
- **Administer Jira**: Granted by the _Jira Administrators_ global
permission. There is a default group for this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
- **Administer a project in Jira**: Granted by the _Administer projects_
project permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access a project in Jira**: Granted by the _Browse projects_ project
permission for a project. This can be
granted to a user, a group, a project role, and more.
See [Managing project
permissions](https://confluence.atlassian.com/x/yodKLg) for details.
- **Access Jira**: Granted by the _Jira Users_ global permission. Users
in the default product access group (for example,
_jira-software-users-acmesite_) have this permission.
See [Manage groups](https://confluence.atlassian.com/x/24xjL) and
[Managing global permissions](https://confluence.atlassian.com/x/x4dKLg)
for details.
### Anonymous access
Some operations provide support for anonymous access. However, anonymous
access is only available if
the Jira permission needed to access the object or records returned by
the operation is granted to
the _Public_ group. See [Allowing anonymous access to your
project](https://confluence.atlassian.com/x/GDxxLg)
for details.
If an operation is called anonymously and anonymous access is not
available, the operation will return
an error. Note that not all operations that correspond to objects that
can be given public access
provide for anonymous access.
title: Permissions
- anchor: expansion
body: >+
### Expansion
The Jira REST API uses resource expansion, which means that some parts
of a resource are not returned unless specified
in the request. This simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the expand query
parameter and specify the object(s) to be expanded.
If you need to expand nested objects, use the `.` dot notation. If you
need to expand multiple objects, use a
comma-separated list.
For example, the following request expands the `names` and
`renderedFields` properties for the _JRACLOUD-34423_ issue:
`GET issue/JRACLOUD-34423?expand=names,renderedFields`
To discover which object can be expanded, refer to the `expand` property
in the object.
In the JSON example below, the resource declares `widgets` as
expandable.
```json
{
"expand": "widgets",
"self": "https://your-domain.atlassian.net/rest/api/3/resource/KEY-1",
"widgets": {
"widgets": [],
"size": 5
}
}
```
### Pagination
The Jira REST API uses pagination to improve performance. Pagination is
enforced for operations that could return a large
collection of items. When you make a request to a paginated resource,
the response wraps the returned array of values in
a JSON object with paging metadata. For example:
```json
{
"startAt" : 0,
"maxResults" : 10,
"total": 200,
"isLast": false,
"values": [
{ /* result 0 */ },
{ /* result 1 */ },
{ /* result 2 */ }
]
}
```
* `startAt` is the index of the first item returned in the page.
* `maxResults` is the maximum number of items that a page can return.
Each operation can have a different limit for
the number of items returned, and these limits may change without notice. To find the maximum number of items
that an operation could return, set `maxResults` to a large number—for example, over 1000—and if the returned value of `maxResults` is less than the requested value, the returned value is the maximum.
* `total` is the total number of items contained in all pages. This
number **_may change_** as the client
requests the subsequent pages, therefore the client should always assume
that the requested page can be empty. Note
that this property is not returned for all operations.
* `isLast` indicates whether the page returned is the last one. Note
that this property is not returned for all operations.
### Ordering
Some operations support ordering the elements of a response by a field.
Check the documentation for the operation to
confirm whether ordering of a response is supported and which fields can
be used. Responses are listed in ascending order
by default. You can change the order using the `orderby` query parameter
with a `-` or `+` symbol. For example:
* `?orderBy=name` to order by `name` field ascending.
* `?o
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-fieldconfigurationscheme--openapi-original.yml