Atlassian Screens API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Screens API
  description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
  version: 1.0.0
  contact:
    name: Atlassian Developer
    url: https://developer.atlassian.com/cloud/admin/
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-logo:
    url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
  description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Screens
paths:
  /rest/api/3/field/{fieldId}/screens:
    get:
      deprecated: false
      description: Returns a [paginated](#pagination) list of the screens a field is used in.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianGetscreensforfield
      parameters:
      - description: The ID of the field to return screens for.
        in: path
        name: fieldId
        required: true
        schema:
          type: string
      - 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: 100
          format: int32
          type: integer
      - description: Use [expand](#expansion) to include additional information about screens in the response. This parameter accepts `tab` which returns details about the screen tabs the field is used in.
        in: query
        name: expand
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"isLast":false,"maxResults":1,"startAt":0,"total":5,"values":[{"id":10001,"name":"Default Screen","description":"Provides for the update of all system fields.","tab":{"id":10000,"name":"Fields Tab"}}]}'
              schema:
                $ref: '#/components/schemas/PageBeanScreenWithTab'
          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.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      - {}
      summary: Atlassian Get Screens For A Field
      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:jira
        - read:avatar:jira
        - read:project-category:jira
        - read:project:jira
        - read:screen-tab:jira
        state: Beta
      x-atlassian-connect-scope: NONE
  /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/{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:
    get:
      deprecated: false
      description: Returns a [paginated](#pagination) list of all screens or those specified by one or more screen IDs.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianGetscreens
      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: 100
          format: int32
          type: integer
      - description: The list of screen IDs. To include multiple IDs, provide an ampersand-separated list. For example, `id=10000&id=10001`.
        in: query
        name: id
        schema:
          items:
            format: int64
            type: integer
          type: array
          uniqueItems: true
      - description: String used to perform a case-insensitive partial match with screen name.
        in: query
        name: queryString
        schema:
          default: ''
          type: string
      - description: The scope filter string. To filter by multiple scope, provide an ampersand-separated list. For example, `scope=GLOBAL&scope=PROJECT`.
        in: query
        name: scope
        schema:
          items:
            default: ''
            enum:
            - GLOBAL
            - TEMPLATE
            - PROJECT
            type: string
          type: array
          uniqueItems: true
      - description: "[Order](#ordering) the results by a field:\n\n *  `id` Sorts by screen ID.\n *  `name` Sorts by screen name."
        in: query
        name: orderBy
        schema:
          enum:
          - name
          - -name
          - +name
          - id
          - -id
          - +id
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"isLast":true,"maxResults":100,"self":"https://your-domain.atlassian.net/rest/api/3/screens","startAt":0,"total":3,"values":[{"id":1,"name":"Default Screen","description":"Provides for the update all system fields."},{"id":2,"name":"Workflow Screen","description":"This screen is used in the workflow and enables you to assign issues."},{"id":3,"name":"Resolve Issue Screen","description":"Offers the ability to set resolution, change fix versions, and assign an issue."}]}'
              schema:
                $ref: '#/components/schemas/PageBeanScreen'
          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.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Get Screens
      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
        - read:avatar:jira
        - read:project-category:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
    post:
      deprecated: false
      description: Creates a screen with a default field tab.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianCreatescreen
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              description: Enables changes to resolution and linked issues.
              name: Resolve Security Issue Screen
            schema:
              $ref: '#/components/schemas/ScreenDetails'
        required: true
      responses:
        '201':
          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 required permissions.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Create 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
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
    ScreenWithTab:
      additionalProperties: false
      description: A screen with tab details.
      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.
        tab:
          allOf:
          - $ref: '#/components/schemas/ScreenableTab'
          description: The tab for the screen.
      type: object
    ScreenDetails:
      additionalProperties: false
      description: Details of a screen.
      properties:
        description:
          description: The description of the screen. The maximum length is 255 characters.
          type: string
          writeOnly: true
        name:
          description: The name of the screen. The name must be unique. The maximum length is 255 characters.
          type: string
          writeOnly: true
      required:
      - name
      type: object
    Scope:
      additionalProperties: true
      description: The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO).
      properties:
        project:
          allOf:
          - $ref: '#/components/schemas/ProjectDetails'
          description: The project the item has scope in.
          readOnly: true
        type:
          description: The type of scope.
          enum:
          - PROJECT
          - TEMPLATE
          readOnly: true
          type: string
      type: object
    UpdatedProjectCategory:
      additionalProperties: false
      description: A project category.
      properties:
        description:
          description: The name of the project category.
          readOnly: true
          type: string
        id:
          description: The ID of the project category.
          readOnly: true
          type: string
        name:
          description: The description of the project category.
          readOnly: true
          type: string
        self:
          description: The URL of the project category.
          readOnly: true
          type: string
      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
    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
    UpdateScreenDetails:
      additionalProperties: false
      description: Details of a screen.
      properties:
        description:
          description: The description of the screen. The maximum length is 255 characters.
          type: string
          writeOnly: true
        name:
          description: The name of the screen. The name must be unique. The maximum length is 255 characters.
          type: string
          writeOnly: true
      type: object
    PageBeanScreen:
      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/Screen'
          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
    AvatarUrlsBean:
      additionalProperties: false
      properties:
        16x16:
          description: The URL of the item's 16x16 pixel avatar.
          format: uri
          type: string
        24x24:
          description: The URL of the item's 24x24 pixel avatar.
          format: uri
          type: string
        32x32:
          description: The URL of the item's 32x32 pixel avatar.
          format: uri
          type: string
        48x48:
          description: The URL of the item's 48x48 pixel avatar.
          format: uri
          type: string
      type: object
    ProjectDetails:
      additionalProperties: false
      description: Details about a project.
      properties:
        avatarUrls:
          allOf:
          - $ref: '#/components/schemas/AvatarUrlsBean'
          description: The URLs of the project's avatars.
          readOnly: true
        id:
          description: The ID of the project.
          type: string
        key:
          description: The key of the project.
          readOnly: true
          type: string
        name:
          description: The name of the project.
          readOnly: true
          type: string
        projectCategory:
          allOf:
          - $ref: '#/components/schemas/UpdatedProjectCategory'
          description: The category the project belongs to.
          readOnly: true
        projectTypeKey:
          description: The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project.
          enum:
          - software
          - service_desk
          - business
          readOnly: true
          type: string
        self:
          description: The URL of the project details.
          readOnly: true
          type: string
        simplified:
          description: Whether or not the project is simplified.
          readOnly: true
          type: boolean
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization for Atlassian Cloud APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:org:admin: Read organization information.
            write:org:admin: Modify organization settings.
            read:user:admin: Read user information.
            write:user:admin: Modify user accounts.
            read:policy:admin: Read organization policies.
            write:policy:admin: Modify organization policies.
            read:event:admin: Read organization events.
externalDocs:
  description: Atlassian Admin REST API Documentation
  url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/