Create UI modification

POST

/rest/api/3/uiModifications

Creates a UI modification. UI modification can only be created by Forge apps.

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.

Permissions required:

None if the UI modification is created without contexts.

Browse projects project permission for one or more projects, if the UI modification is created with contexts.

The new write:app-data:jira OAuth scope is 100% optional now, and not using it won't break your app. However, we recommend adding it to your app's scope list because we will eventually make it mandatory.

Request

Body Params application/json

Examples

Responses

🟢201Created

application/json

Returned if the UI modification is created.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

Request Example

Shell

JavaScript

Java

Swift

curl --location '/rest/api/3/uiModifications' \
--header 'Content-Type: application/json' \
--data '{
    "contexts": [
        {
            "issueTypeId": "10000",
            "projectId": "10000",
            "viewType": "GIC"
        },
        {
            "issueTypeId": "10001",
            "projectId": "10000",
            "viewType": "IssueView"
        },
        {
            "issueTypeId": "10002",
            "projectId": "10000",
            "viewType": "IssueTransition"
        },
        {
            "issueTypeId": "10003",
            "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"
}'

Response Example

201 - Success

{"id":"d7dbda8a-6239-4b63-8e13-a5ef975c8e61","self":"https://api.atlassian.com/ex/jira/{cloudid}/rest/api/2/uiModifications/d7dbda8a-6239-4b63-8e13-a5ef975c8e61"}

Modified at 2025-07-16 07:18:01

Get UI modifications

Delete UI modification