Atlassian Jira Screens API
The Atlassian Jira Screens API enables creating and managing issue screens, tabs, and field layouts within Jira.
OpenAPI Specification
components:
schemas:
Screen:
additionalProperties: false
description: A screen.
properties:
description:
description: The description of the screen.
readOnly: true
type: string
id:
description: The ID of the screen.
format: int64
readOnly: true
type: integer
name:
description: The name of the screen.
readOnly: true
type: string
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the screen.
type: object
ScreenableTab:
additionalProperties: false
description: A screen tab.
properties:
id:
description: The ID of the screen tab.
format: int64
readOnly: true
type: integer
name:
description: The name of the screen tab. The maximum length is 255 characters.
type: string
required:
- name
type: object
ScreenableField:
additionalProperties: false
description: A screen tab field.
properties:
id:
description: The ID of the screen tab field.
readOnly: true
type: string
name:
description: >-
The name of the screen tab field. Required on create and update. The
maximum length is 255 characters.
type: string
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/screens/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/screens/addToDefault/{fieldId}:
post:
deprecated: false
description: >-
Adds a field to the default tab of the default
screen.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAddfieldtodefaultscreen
parameters:
- description: The ID of the field.
in: path
name: fieldId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 it not found or the field is already present.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Add Field To Default Screen
tags:
- Screens
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:project:jira
- read:screen:jira
- write:screen:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/tabs:
get:
deprecated: false
description: >-
Returns the list of tabs for a bulk of
screens.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetbulkscreentabs
parameters:
- description: >-
The list of screen IDs. To include multiple screen IDs, provide an
ampersand-separated list. For example,
`screenId=10000&screenId=10001`.
in: query
name: screenId
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: >-
The list of tab IDs. To include multiple tab IDs, provide an
ampersand-separated list. For example, `tabId=10000&tabId=10001`.
in: query
name: tabId
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. The maximum number
is 100,
in: query
name: maxResult
schema:
default: 100
format: int32
type: integer
responses:
'200':
content:
application/json:
example: >-
{"isLast":true,"maxResults":100,"startAt":0,"total":2,"values":[{"screenId":10000,"tabId":10001,"tabName":"My
Custom Tab 1"},{"screenId":10001,"tabId":10002,"tabName":"My
Custom Tab 2"}]}
description: Returned if the request is successful.
'400':
description: Returned if the screen ID or the tab ID is empty.
'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-project
summary: Atlassian Get Bulk Screen Tabs
tags:
- Screen Tabs
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screen-tab:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}:
delete:
deprecated: false
description: >-
Deletes a screen. A screen cannot be deleted if it is used in a screen
scheme, workflow, or workflow draft.<br><br>Only screens used in classic
projects can be deleted.
operationId: atlassianDeletescreen
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
responses:
'204':
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The screen is used in a screen
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 manage
screens."],"errors":{}}
description: Returned if the user does not have the necessary permission.
'404':
content:
application/json:
example: '{"errorMessages":["The screen was not found."],"errors":{}}'
description: Returned if the screen is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
summary: Atlassian Delete Screen
tags:
- Screens
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- delete:screen:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates a screen. Only screens used in classic projects can be
updated.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianUpdatescreen
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
description: >-
Enables changes to resolution and linked issues for
accessibility related issues.
name: Resolve Accessibility Issue Screen
schema:
$ref: '#/components/schemas/UpdateScreenDetails'
required: true
responses:
'200':
content:
application/json:
example: >-
{"id":10005,"name":"Resolve Security Issue
Screen","description":"Enables changes to resolution and linked
issues."}
schema:
$ref: '#/components/schemas/Screen'
description: Returned if the request is successful.
'400':
content:
application/json:
example: >-
{"errorMessages":["The name is used by another
screen."],"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 manage
screens."],"errors":{}}
description: Returned if the user does not have the necessary permission.
'404':
content:
application/json:
example: '{"errorMessages":["The screen was not found."],"errors":{}}'
description: Returned if the screen is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
summary: Atlassian Update Screen
tags:
- Screens
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:project:jira
- read:screen:jira
- write:screen:jira
- read:avatar:jira
- read:project-category:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/availableFields:
get:
deprecated: false
description: >-
Returns the fields that can be added to a tab on a
screen.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetavailablescreenfields
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ScreenableField'
type: array
description: Returned if the request is successful.
'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 screen is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Get Available Screen Fields
tags:
- Screens
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screen-field:jira
- read:screenable-field:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/tabs:
get:
deprecated: false
description: >-
Returns the list of tabs for a
screen.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).<br> * *Administer projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) when the project
key is specified, providing that the screen is associated with the
project through a Screen Scheme and Issue Type Screen Scheme.
operationId: atlassianGetallscreentabs
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The key of the project.
in: query
name: projectKey
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ScreenableTab'
type: array
description: Returned if the request is successful.
'400':
description: Returned if the screen ID is invalid.
'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 screen is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Get All Screen Tabs
tags:
- Screen Tabs
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screen-tab:jira
state: Beta
x-atlassian-connect-scope: ADMIN
post:
deprecated: false
description: >-
Creates a tab for a screen.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAddscreentab
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
name: Fields Tab
schema:
$ref: '#/components/schemas/ScreenableTab'
required: true
responses:
'200':
content:
application/json:
example: '{"id":10000,"name":"Fields Tab"}'
schema:
$ref: '#/components/schemas/ScreenableTab'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 screen is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Create Screen Tab
tags:
- Screen Tabs
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screen-tab:jira
- write:screen-tab:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/tabs/{tabId}:
delete:
deprecated: false
description: >-
Deletes a screen tab.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianDeletescreentab
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
responses:
'204':
description: Returned if the request is successful.
'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 screen or screen tab is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Delete Screen Tab
tags:
- Screen Tabs
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- delete:screen-tab:jira
state: Beta
x-atlassian-connect-scope: ADMIN
put:
deprecated: false
description: >-
Updates the name of a screen tab.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianRenamescreentab
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScreenableTab'
required: true
responses:
'200':
content:
application/json:
example: '{"id":10000,"name":"Fields Tab"}'
schema:
$ref: '#/components/schemas/ScreenableTab'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 screen or screen tab is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Update Screen Tab
tags:
- Screen Tabs
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screen-tab:jira
- write:screen-tab:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/tabs/{tabId}/fields:
get:
deprecated: false
description: >-
Returns all fields for a screen
tab.<br><br>**[Permissions](#permissions) required:**<br><br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).<br> * *Administer projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) when the project
key is specified, providing that the screen is associated with the
project through a Screen Scheme and Issue Type Screen Scheme.
operationId: atlassianGetallscreentabfields
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
- description: The key of the project.
in: query
name: projectKey
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ScreenableField'
type: array
description: Returned if the request is successful.
'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 screen or screen tab is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Get All Screen Tab Fields
tags:
- Screen Tab Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screenable-field:jira
state: Beta
x-atlassian-connect-scope: ADMIN
post:
deprecated: false
description: >-
Adds a field to a screen tab.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianAddscreentabfield
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
requestBody:
content:
application/json:
example:
fieldId: summary
schema:
$ref: '#/components/schemas/AddFieldBean'
required: true
responses:
'200':
content:
application/json:
example: '{"id":"summary","name":"Summary"}'
schema:
$ref: '#/components/schemas/ScreenableField'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 screen, screen tab, or field is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Add Screen Tab Field
tags:
- Screen Tab Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- read:screenable-field:jira
- write:screenable-field:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/tabs/{tabId}/fields/{id}:
delete:
deprecated: false
description: >-
Removes a field from a screen tab.<br><br>**[Permissions](#permissions)
required:** *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianRemovescreentabfield
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
- description: The ID of the field.
in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 screen, screen tab, or field is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Remove Screen Tab Field
tags:
- Screen Tab Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- delete:screenable-field:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/tabs/{tabId}/fields/{id}/move:
post:
deprecated: false
description: >-
Moves a screen tab field.<br><br>If `after` and `position` are provided
in the request, `position` is
ignored.<br><br>**[Permissions](#permissions) required:** *Administer
Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianMovescreentabfield
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
- description: The ID of the field.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MoveFieldBean'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 screen, screen tab, or field is not found or the
field can't be moved to the requested position.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Move Screen Tab Field
tags:
- Screen Tab Fields
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- write:screenable-field:jira
state: Beta
x-atlassian-connect-scope: ADMIN
/rest/api/3/screens/{screenId}/tabs/{tabId}/move/{pos}:
post:
deprecated: false
description: >-
Moves a screen tab.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianMovescreentab
parameters:
- description: The ID of the screen.
in: path
name: screenId
required: true
schema:
format: int64
type: integer
- description: The ID of the screen tab.
in: path
name: tabId
required: true
schema:
format: int64
type: integer
- description: The position of tab. The base index is 0.
in: path
name: pos
required: true
schema:
format: int32
type: integer
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'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 screen or screen tab is not found or the position is
invalid.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Move Screen Tab
tags:
- Screen Tabs
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- write:screen:jira
state: Beta
x-atlassian-connect-scope: ADMIN
servers:
- url: https://your-domain.atlassian.net
tags:
- name: Screen Tab Fields
- name: Screen Tabs
- name: Screens
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:
-
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-screens--openapi-original.yml