Atlassian Jira Issue Type Scheme API
The Atlassian Jira Issue Type Scheme API enables managing and customizing issue type schemes within Jira projects.
OpenAPI Specification
components:
schemas:
PageBeanIssueTypeSchemeMapping:
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/IssueTypeSchemeMapping'
readOnly: true
type: array
type: object
PageBeanIssueTypeSchemeProjects:
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/IssueTypeSchemeProjects'
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/issuetypescheme/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/issuetypescheme/mapping:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of issue type scheme
items.<br><br>Only issue type scheme items used in classic projects are
returned.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetissuetypeschemesmapping
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 issue type scheme IDs. To include multiple IDs, provide
an ampersand-separated list. For example,
`issueTypeSchemeId=10000&issueTypeSchemeId=10001`.
in: query
name: issueTypeSchemeId
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":100,"startAt":0,"total":4,"values":[{"issueTypeSchemeId":"10000","issueTypeId":"10000"},{"issueTypeSchemeId":"10000","issueTypeId":"10001"},{"issueTypeSchemeId":"10000","issueTypeId":"10002"},{"issueTypeSchemeId":"10001","issueTypeId":"10000"}]}
schema:
$ref: '#/components/schemas/PageBeanIssueTypeSchemeMapping'
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 required permissions.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Issue Type Scheme Items
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/project:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of issue type schemes and, for
each issue type scheme, a list of the projects that use it.<br><br>Only
issue type schemes used in classic projects are
returned.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetissuetypeschemeforprojects
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 project IDs, provide an
ampersand-separated list. For example,
`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":100,"startAt":0,"total":3,"values":[{"issueTypeScheme":{"id":"10000","name":"Default
Issue Type Scheme","description":"Default issue type scheme is
the list of global issue types. All newly created issue types
will automatically be added to this
scheme.","defaultIssueTypeId":"10003","isDefault":true},"projectIds":["10000","10001"]},{"issueTypeScheme":{"id":"10001","name":"SUP:
Kanban Issue Type Scheme","description":"A collection of issue
types suited to use in a kanban style
project."},"projectIds":["10002"]},{"issueTypeScheme":{"id":"10002","name":"HR:
Scrum issue type
scheme","description":"","defaultIssueTypeId":"10004","issueTypes":{"isLast":true,"maxResults":100,"startAt":0,"total":1,"values":[{"description":"Improvement
Issue
Type","hierarchyLevel":-1,"iconUrl":"www.example.com","id":"1000L","name":"Improvements","subtask":true}]}},"projectIds":["10003","10004","10005"]}]}
schema:
$ref: '#/components/schemas/PageBeanIssueTypeSchemeProjects'
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 required permissions.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Get Issue Type Schemes For Projects
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Assigns an issue type scheme to a project.<br><br>If any issues in the
project are assigned issue types not present in the new scheme, the
operation will fail. To complete the assignment those issues must be
updated to use issue types in the new scheme.<br><br>Issue type schemes
can only be assigned to classic
projects.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAssignissuetypeschemetoproject
parameters: []
requestBody:
content:
application/json:
example:
issueTypeSchemeId: '10000'
projectId: '10000'
schema:
$ref: '#/components/schemas/IssueTypeSchemeProjectAssociation'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["This issue type scheme can't be assigned to
the project. This is because some issues in this project use
issue types not present in the scheme. Before assigning the
scheme to the project, update the issue types on these issues:
7"],"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 issue
type schemes."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
description: Returned if the issue type scheme or the project is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Assign Issue Type Scheme To Project
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
- write:project:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/{issueTypeSchemeId}:
delete:
deprecated: false
description: >-
Deletes an issue type scheme.<br><br>Only issue type schemes used in
classic projects can be deleted.<br><br>Any projects assigned to the
scheme are reassigned to the default issue type
scheme.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeleteissuetypescheme
parameters:
- description: The ID of the issue type scheme.
in: path
name: issueTypeSchemeId
required: true
schema:
format: int64
type: integer
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the issue type scheme is deleted.
'400':
content:
application/json:
example: >-
{"errorMessages":["The default issue type scheme can't be
removed."],"errors":{}}
description: Returned if the request is to delete the default issue type scheme.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
content:
application/json:
example: >-
{"errorMessages":["Only Jira administrators can access issue
type schemes."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
description: Returned if the issue type scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Delete Issue Type Scheme
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
- write:project:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates an issue type scheme.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdateissuetypescheme
parameters:
- description: The ID of the issue type scheme.
in: path
name: issueTypeSchemeId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
defaultIssueTypeId: '10002'
description: >-
A collection of issue types suited to use in a kanban style
project.
name: Kanban Issue Type Scheme
schema:
$ref: '#/components/schemas/IssueTypeSchemeUpdateDetails'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The default issue type has to be one of the
issue types of the scheme."],"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 issue
type schemes."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
description: Returned if the issue type scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Update Issue Type Scheme
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/{issueTypeSchemeId}/issuetype:
put:
deprecated: false
description: >-
Adds issue types to an issue type scheme.<br><br>The added issue types
are appended to the issue types list.<br><br>If any of the issue types
exist in the issue type scheme, the operation fails and no issue types
are added.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAddissuetypestoissuetypescheme
parameters:
- description: The ID of the issue type scheme.
in: path
name: issueTypeSchemeId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
issueTypeIds:
- '10000'
- '10002'
- '10003'
schema:
$ref: '#/components/schemas/IssueTypeIds'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["These issue types were not added because they
are already present in the issue type scheme: 10002,
10003"],"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 issue
type schemes."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["These issue types were not found: 10000,
10002"],"errors":{}}
description: Returned if the issue type or the issue type scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Add Issue Types To Issue Type Scheme
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/{issueTypeSchemeId}/issuetype/move:
put:
deprecated: false
description: >-
Changes the order of issue types in an issue type scheme.<br><br>The
request body parameters must meet the following requirements:<br><br> * all of the issue types must belong to the issue type scheme.<br> * either `after` or `position` must be provided.<br> * the issue type in
`after` must not be in the issue type
list.<br><br>**[Permissions](#permissions) required:** *Administer Jira*
[global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianReorderissuetypesinissuetypescheme
parameters:
- description: The ID of the issue type scheme.
in: path
name: issueTypeSchemeId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
after: '10008'
issueTypeIds:
- '10001'
- '10004'
- '10002'
schema:
$ref: '#/components/schemas/OrderOfIssueTypes'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme does not include some
of the specified issue types. Issue type IDs missing from the
scheme are: 10007, 10008"],"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 issue
type schemes."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The issue type scheme was not
found."],"errors":{}}
description: Returned if the issue type scheme is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Change Order Of Issue Types
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/issuetypescheme/{issueTypeSchemeId}/issuetype/{issueTypeId}:
delete:
deprecated: false
description: >-
Removes an issue type from an issue type scheme.<br><br>This operation
cannot remove:<br><br> * any issue type used by issues.<br> * any
issue types from the default issue type scheme.<br> * the last standard
issue type from an issue type
scheme.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianRemoveissuetypefromissuetypescheme
parameters:
- description: The ID of the issue type scheme.
in: path
name: issueTypeSchemeId
required: true
schema:
format: int64
type: integer
- description: The ID of the issue type.
in: path
name: issueTypeId
required: true
schema:
format: int64
type: integer
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["Can't remove the last standard issue type
from the issue type scheme."],"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 issue
type schemes."],"errors":{}}
description: Returned if the user does not have the required permissions.
'404':
content:
application/json:
example: >-
{"errorMessages":["The issue type was not found in the issue
type scheme."],"errors":{}}
description: >-
Returned if the issue type scheme is missing or the issue type is
not found in the issue type scheme.
security:
- basicAuth: []
- OAuth2:
- manage:jira-configuration
summary: Atlassian Remove Issue Type From Issue Type Scheme
tags:
- Issue Type Schemes
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:issue-type-scheme:jira
state: Beta
x-atlassian-connect-scope: ADMIN
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Issue Type Schemes
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 oper
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-issuetypescheme--openapi-original.yml