Atlassian UI Modifications (Apps) API

openapi: 3.1.0
info:
  title: Atlassian Admin Account UI Modifications (Apps) 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: UI Modifications (Apps)
paths:
  /rest/api/3/uiModifications/{uiModificationId}:
    delete:
      deprecated: false
      description: Deletes a UI modification. All the contexts that belong to the UI modification are deleted too. UI modification can only be deleted by Forge apps.<br><br>**[Permissions](#permissions) required:** None.
      operationId: atlassianDeleteuimodification
      parameters:
      - description: The ID of the UI modification.
        in: path
        name: uiModificationId
        required: true
        schema:
          type: string
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the UI modification is deleted.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: Returned if the request is not from a Forge app.
        '404':
          description: Returned if the UI modification is not found.
      security:
      - basicAuth: []
      - OAuth2: []
      summary: Atlassian Delete Ui Modification
      tags:
      - UI Modifications (Apps)
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: NONE
    put:
      deprecated: false
      description: Updates a UI modification. UI modification can only be updated by Forge apps.<br><br>Each UI modification can define up to 1000 contexts. The same context can be assigned to maximum 100 UI modifications.<br><br>**[Permissions](#permissions) required:**<br><br> *  *None* if the UI modification is created without contexts.<br> *  *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for one or more projects, if the UI modification is created with contexts.
      operationId: atlassianUpdateuimodification
      parameters:
      - description: The ID of the UI modification.
        in: path
        name: uiModificationId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              contexts:
              - issueTypeId: '10000'
                projectId: '10000'
                viewType: GIC
              - issueTypeId: '10001'
                projectId: '10000'
                viewType: IssueView
              data: '{field: ''Story Points'', config: {hidden: true}}'
              name: Updated Reveal Story Points
            schema:
              $ref: '#/components/schemas/UpdateUiModificationDetails'
        description: Details of the UI modification.
        required: true
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the UI modification is updated.
        '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 request is not from a Forge app.
        '404':
          content:
            application/json:
              example: '{"details":{"issueTypesNotFound":{"10001":["10000","10001"]},"projectNotFound":["10000"]},"errorMessages":["Project with ID ''10000'' was not found.","Project with ID ''10001''. The following issue types were not found: [10000, 10001]"],"errors":{}}'
              schema:
                $ref: '#/components/schemas/DetailedErrorCollection'
          description: Returned if the UI modification, a project or an issue type in the context are not found.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Update Ui Modification
      tags:
      - UI Modifications (Apps)
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: NONE
  /rest/api/3/uiModifications:
    get:
      deprecated: false
      description: Gets UI modifications. UI modifications can only be retrieved by Forge apps.<br><br>**[Permissions](#permissions) required:** None.
      operationId: atlassianGetuimodifications
      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: "Use expand to include additional information in the response. This parameter accepts a comma-separated list. Expand options include:\n\n *  `data` Returns UI modification data.\n *  `contexts` Returns UI modification contexts."
        in: query
        name: expand
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"isLast":true,"maxResults":100,"startAt":0,"total":3,"values":[{"id":"d7dbda8a-6239-4b63-8e13-a5ef975c8e61","name":"Reveal Story Points","description":"Reveals Story Points field when any Sprint is selected.","self":"https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d7dbda8a-6239-4b63-8e13-a5ef975c8e61","data":"{field: ''Story Points'', config: {hidden: false}}","contexts":[{"id":"1533537a-bda3-4ac6-8481-846128cd9ef4","projectId":"10000","issueTypeId":"10000","viewType":"GIC","isAvailable":true},{"id":"c016fefa-6eb3-40c9-8596-4c4ef273e67c","projectId":"10000","issueTypeId":"10001","viewType":"IssueView","isAvailable":true}]},{"id":"e4fe8db5-f82f-416b-a3aa-b260b55da577","name":"Set Assignee","description":"Sets the Assignee field automatically.","self":"https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/e4fe8db5-f82f-416b-a3aa-b260b55da577","contexts":[{"id":"8b3740f9-8780-4958-8228-69dcfbda11d9","projectId":"10000","issueTypeId":"10000","viewType":"GIC","isAvailable":true}]},{"id":"1453f993-79ce-4389-a36d-eb72d5c85dd6","name":"Hide Labels","description":"Hides Labels if any component is provided.","self":"https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/1453f993-79ce-4389-a36d-eb72d5c85dd6","contexts":[]},{"id":"d3f4097e-8d8e-451e-9fb6-27c3c8c3bfff","name":"Wildcard example","description":"This context is applied to all issue types","self":"https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d3f4097e-8d8e-451e-9fb6-27c3c8c3bfff","contexts":[{"id":"521f2181-5d5e-46ea-9fc9-871bbf245b8b","projectId":"10000","issueTypeId":null,"viewType":"GIC","isAvailable":true}]}]}'
              schema:
                $ref: '#/components/schemas/PageBeanUiModificationDetails'
          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 request is not from a Forge app.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Get Ui Modifications
      tags:
      - UI Modifications (Apps)
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: NONE
    post:
      deprecated: false
      description: Creates a UI modification. UI modification can only be created by Forge apps.<br><br>Each app can define up to 3000 UI modifications. Each UI modification can define up to 1000 contexts. The same context can be assigned to maximum 100 UI modifications.<br><br>**[Permissions](#permissions) required:**<br><br> *  *None* if the UI modification is created without contexts.<br> *  *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for one or more projects, if the UI modification is created with contexts.
      operationId: atlassianCreateuimodification
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              contexts:
              - issueTypeId: '10000'
                projectId: '10000'
                viewType: GIC
              - issueTypeId: '10001'
                projectId: '10000'
                viewType: IssueView
              - issueTypeId: '10002'
                projectId: '10000'
                viewType: null
              data: '{field: ''Story Points'', config: {hidden: false}}'
              description: Reveals Story Points field when any Sprint is selected.
              name: Reveal Story Points
            schema:
              $ref: '#/components/schemas/CreateUiModificationDetails'
        description: Details of the UI modification.
        required: true
      responses:
        '201':
          content:
            application/json:
              example: '{"id":"d7dbda8a-6239-4b63-8e13-a5ef975c8e61","self":"https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d7dbda8a-6239-4b63-8e13-a5ef975c8e61"}'
              schema:
                $ref: '#/components/schemas/UiModificationIdentifiers'
          description: Returned if the UI modification is created.
        '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 request is not from a Forge app.
        '404':
          content:
            application/json:
              example: '{"details":{"issueTypesNotFound":{"10001":["10000","10001"]},"projectNotFound":["10000"]},"errorMessages":["Project with ID ''10000'' was not found.","Project with ID ''10001''. The following issue types were not found: [10000, 10001]"],"errors":{}}'
              schema:
                $ref: '#/components/schemas/DetailedErrorCollection'
          description: Returned if a project or an issue type in the context are not found.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Create Ui Modification
      tags:
      - UI Modifications (Apps)
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-connect-scope: NONE
components:
  schemas:
    UpdateUiModificationDetails:
      additionalProperties: false
      description: The details of a UI modification.
      properties:
        contexts:
          description: List of contexts of the UI modification. The maximum number of contexts is 1000. If provided, replaces all existing contexts.
          items:
            $ref: '#/components/schemas/UiModificationContextDetails'
          type: array
          writeOnly: true
        data:
          description: The data of the UI modification. The maximum size of the data is 50000 characters.
          type: string
          writeOnly: true
        description:
          description: The description of the UI modification. The maximum length is 255 characters.
          type: string
          writeOnly: true
        name:
          description: The name of the UI modification. The maximum length is 255 characters.
          type: string
          writeOnly: true
      type: object
    PageBeanUiModificationDetails:
      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/UiModificationDetails'
          readOnly: true
          type: array
      type: object
    UiModificationDetails:
      additionalProperties: false
      description: The details of a UI modification.
      properties:
        contexts:
          description: List of contexts of the UI modification. The maximum number of contexts is 1000.
          items:
            $ref: '#/components/schemas/UiModificationContextDetails'
          readOnly: true
          type: array
        data:
          description: The data of the UI modification. The maximum size of the data is 50000 characters.
          readOnly: true
          type: string
        description:
          description: The description of the UI modification. The maximum length is 255 characters.
          readOnly: true
          type: string
        id:
          description: The ID of the UI modification.
          readOnly: true
          type: string
        name:
          description: The name of the UI modification. The maximum length is 255 characters.
          readOnly: true
          type: string
        self:
          description: The URL of the UI modification.
          readOnly: true
          type: string
      required:
      - id
      - name
      - self
      type: object
    DetailedErrorCollection:
      additionalProperties: false
      properties:
        details:
          additionalProperties: {}
          description: Map of objects representing additional details for an error
          type: object
        errorMessages:
          description: The list of error messages produced by this operation. For example, "input parameter 'key' must be provided"
          items:
            type: string
          type: array
        errors:
          additionalProperties:
            type: string
          description: 'The list of errors by parameter returned by the operation. For example,"projectKey": "Project keys must start with an uppercase letter, followed by one or more uppercase alphanumeric characters."'
          type: object
      type: object
    CreateUiModificationDetails:
      additionalProperties: false
      description: The details of a UI modification.
      properties:
        contexts:
          description: List of contexts of the UI modification. The maximum number of contexts is 1000.
          items:
            $ref: '#/components/schemas/UiModificationContextDetails'
          type: array
          writeOnly: true
        data:
          description: The data of the UI modification. The maximum size of the data is 50000 characters.
          type: string
          writeOnly: true
        description:
          description: The description of the UI modification. The maximum length is 255 characters.
          type: string
          writeOnly: true
        name:
          description: The name of the UI modification. The maximum length is 255 characters.
          type: string
          writeOnly: true
      required:
      - name
      type: object
    UiModificationIdentifiers:
      additionalProperties: false
      description: Identifiers for a UI modification.
      properties:
        id:
          description: The ID of the UI modification.
          readOnly: true
          type: string
        self:
          description: The URL of the UI modification.
          readOnly: true
          type: string
      required:
      - id
      - self
      type: object
    UiModificationContextDetails:
      additionalProperties: false
      description: The details of a UI modification's context, which define where to activate the UI modification.
      properties:
        id:
          description: The ID of the UI modification context.
          readOnly: true
          type: string
        isAvailable:
          description: Whether a context is available. For example, when a project is deleted the context becomes unavailable.
          readOnly: true
          type: boolean
        issueTypeId:
          description: The issue type ID of the context. Null is treated as a wildcard, meaning the UI modification will be applied to all issue types. Each UI modification context can have a maximum of one wildcard.
          type: string
        projectId:
          description: The project ID of the context. Null is treated as a wildcard, meaning the UI modification will be applied to all projects. Each UI modification context can have a maximum of one wildcard.
          type: string
        viewType:
          description: The view type of the context. Only `GIC`(Global Issue Create) and `IssueView` are supported. Null is treated as a wildcard, meaning the UI modification will be applied to all view types. Each UI modification context can have a maximum of one wildcard.
          enum:
          - GIC
          - IssueView
          type: string
      type: object
      writeOnly: true
  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/