Atlassian Screen Schemes API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Screen Schemes 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: Screen Schemes
paths:
  /rest/api/3/screenscheme/{screenSchemeId}:
    delete:
      deprecated: false
      description: Deletes a screen scheme. A screen scheme cannot be deleted if it is used in an issue type screen scheme.<br><br>Only screens schemes used in classic projects can be deleted.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianDeletescreenscheme
      parameters:
      - description: The ID of the screen scheme.
        in: path
        name: screenSchemeId
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Returned if the screen scheme is deleted.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The screen scheme cannot be deleted as it is in use in an issue type screen scheme."],"errors":{}}'
          description: Returned if the screen scheme is used in an issue type screen scheme.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: '{"errorMessages":["Only Jira administrators can access screen schemes."],"errors":{}}'
          description: Returned if the user does not have the necessary permission.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["The screen scheme was not found."],"errors":{}}'
          description: Returned if the screen scheme is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Delete Screen Scheme
      tags:
      - Screen Schemes
      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-scheme:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
    put:
      deprecated: false
      description: Updates a screen scheme. Only screen schemes used in classic projects can be updated.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianUpdatescreenscheme
      parameters:
      - description: The ID of the screen scheme.
        in: path
        name: screenSchemeId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: Employee screen scheme v2
              screens:
                create: '10019'
                default: '10018'
            schema:
              $ref: '#/components/schemas/UpdateScreenSchemeDetails'
        description: The screen scheme update details.
        required: true
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The name is used by another 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 screen schemes."],"errors":{}}'
          description: Returned if the user does not have the required permissions.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["The screen scheme was not found."],"errors":{}}'
          description: Returned if the screen scheme or a screen used as one of the screen types is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Update Screen Scheme
      tags:
      - Screen 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:screen-scheme:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
  /rest/api/3/screenscheme:
    get:
      deprecated: false
      description: Returns a [paginated](#pagination) list of screen schemes.<br><br>Only screen schemes used in classic projects are returned.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianGetscreenschemes
      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: 25
          format: int32
          type: integer
      - description: The list of screen scheme 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: Use [expand](#expansion) include additional information in the response. This parameter accepts `issueTypeScreenSchemes` that, for each screen schemes, returns information about the issue type screen scheme the screen scheme is assigned to.
        in: query
        name: expand
        schema:
          default: ''
          type: string
      - description: String used to perform a case-insensitive partial match with screen scheme name.
        in: query
        name: queryString
        schema:
          default: ''
          type: string
      - description: "[Order](#ordering) the results by a field:\n\n *  `id` Sorts by screen scheme ID.\n *  `name` Sorts by screen scheme 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/screenscheme?maxResults=25&startAt=0","startAt":0,"total":2,"values":[{"id":10010,"name":"Employee screen scheme","description":"Manage employee data","screens":{"default":10017,"edit":10019,"create":10019,"view":10020},"issueTypeScreenSchemes":{"isLast":true,"maxResults":100,"startAt":0,"total":1,"values":[{"id":"10000","name":"Office issue type screen scheme","description":"Managing office projects"}]}},{"id":10032,"name":"Office screen scheme","description":"Manage office data","screens":{"default":10020}}]}'
              schema:
                $ref: '#/components/schemas/PageBeanScreenScheme'
          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 Screen Schemes
      tags:
      - Screen Schemes
      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-scheme:jira
        - read:issue-type-screen-scheme:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
    post:
      deprecated: false
      description: Creates a screen scheme.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianCreatescreenscheme
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              description: Manage employee data
              name: Employee screen scheme
              screens:
                default: 10017
                edit: 10019
                view: 10020
            schema:
              $ref: '#/components/schemas/ScreenSchemeDetails'
        required: true
      responses:
        '201':
          content:
            application/json:
              example: '{"id":10001}'
              schema:
                $ref: '#/components/schemas/ScreenSchemeId'
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The name is used by another 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 screen schemes."],"errors":{}}'
          description: Returned if the user does not have the required permissions.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["One or more screens assigned to screen types was not found."],"errors":{}}'
          description: Returned if a screen used as one of the screen types in the screen scheme is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Create Screen Scheme
      tags:
      - Screen 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:screen-scheme:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
components:
  schemas:
    ScreenSchemeId:
      additionalProperties: false
      description: The ID of a screen scheme.
      properties:
        id:
          description: The ID of the screen scheme.
          format: int64
          readOnly: true
          type: integer
      required:
      - id
      type: object
    ScreenTypes:
      additionalProperties: false
      description: The IDs of the screens for the screen types of the screen scheme.
      properties:
        create:
          description: The ID of the create screen.
          format: int64
          type: integer
        default:
          description: The ID of the default screen. Required when creating a screen scheme.
          format: int64
          type: integer
        edit:
          description: The ID of the edit screen.
          format: int64
          type: integer
        view:
          description: The ID of the view screen.
          format: int64
          type: integer
      required:
      - defaultScreen
      type: object
      writeOnly: true
    UpdateScreenTypes:
      additionalProperties: false
      description: The IDs of the screens for the screen types of the screen scheme.
      properties:
        create:
          description: The ID of the create screen. To remove the screen association, pass a null.
          type: string
          writeOnly: true
        default:
          description: The ID of the default screen. When specified, must include a screen ID as a default screen is required.
          type: string
          writeOnly: true
        edit:
          description: The ID of the edit screen. To remove the screen association, pass a null.
          type: string
          writeOnly: true
        view:
          description: The ID of the view screen. To remove the screen association, pass a null.
          type: string
          writeOnly: true
      type: object
      writeOnly: true
    IssueTypeScreenScheme:
      additionalProperties: false
      description: Details of an issue type screen scheme.
      properties:
        description:
          description: The description of the issue type screen scheme.
          type: string
        id:
          description: The ID of the issue type screen scheme.
          type: string
        name:
          description: The name of the issue type screen scheme.
          type: string
      required:
      - id
      - name
      type: object
    ScreenScheme:
      additionalProperties: false
      description: A screen scheme.
      properties:
        description:
          description: The description of the screen scheme.
          type: string
        id:
          description: The ID of the screen scheme.
          format: int64
          type: integer
        issueTypeScreenSchemes:
          allOf:
          - $ref: '#/components/schemas/PageBeanIssueTypeScreenScheme'
          description: Details of the issue type screen schemes associated with the screen scheme.
        name:
          description: The name of the screen scheme.
          type: string
        screens:
          allOf:
          - $ref: '#/components/schemas/ScreenTypes'
          description: The IDs of the screens for the screen types of the screen scheme.
      type: object
    PageBeanIssueTypeScreenScheme:
      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/IssueTypeScreenScheme'
          readOnly: true
          type: array
      type: object
    PageBeanScreenScheme:
      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/ScreenScheme'
          readOnly: true
          type: array
      type: object
    ScreenSchemeDetails:
      additionalProperties: false
      description: Details of a screen scheme.
      properties:
        description:
          description: The description of the screen scheme. The maximum length is 255 characters.
          type: string
          writeOnly: true
        name:
          description: The name of the screen scheme. The name must be unique. The maximum length is 255 characters.
          type: string
          writeOnly: true
        screens:
          allOf:
          - $ref: '#/components/schemas/ScreenTypes'
          description: The IDs of the screens for the screen types of the screen scheme. Only screens used in classic projects are accepted.
      required:
      - name
      - screens
      type: object
    UpdateScreenSchemeDetails:
      additionalProperties: false
      description: Details of a screen scheme.
      properties:
        description:
          description: The description of the screen scheme. The maximum length is 255 characters.
          type: string
          writeOnly: true
        name:
          description: The name of the screen scheme. The name must be unique. The maximum length is 255 characters.
          type: string
          writeOnly: true
        screens:
          allOf:
          - $ref: '#/components/schemas/UpdateScreenTypes'
          description: The IDs of the screens for the screen types of the screen scheme. Only screens used in classic projects are accepted.
      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/