Atlassian
Atlassian Issue Priorities API

The Issue Priorities API from Atlassian — 5 operation(s) for issue priorities.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: Atlassian Admin Account Issue Priorities 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: Issue Priorities
paths:
  /rest/api/3/priority/default:
    put:
      deprecated: false
      description: Sets default issue priority.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianSetdefaultpriority
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              id: '3'
            schema:
              $ref: '#/components/schemas/SetDefaultPriorityRequest'
        required: true
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The id has to be provided."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request isn't valid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: '{"errorMessages":["You are not authorized to perform this action. Administrator privileges are required."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the user doesn't have the necessary permission.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["Priority with ID 10000 not found."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the issue priority isn't found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Set Default Priority
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: ADMIN
  /rest/api/3/priority/move:
    put:
      deprecated: false
      description: Changes the order of issue priorities.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianMovepriorities
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              after: '10003'
              ids:
              - '10004'
              - '10005'
            schema:
              $ref: '#/components/schemas/ReorderIssuePriorities'
        required: true
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The ids must contain no more than 1,000 items."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request isn't valid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: '{"errorMessages":["You are not authorized to perform this action. Administrator privileges are required."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the user doesn't have the necessary permission.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["Priority with ID 10000 not found."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the issue priority isn't found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Move Priorities
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: ADMIN
  /rest/api/3/priority/search:
    get:
      deprecated: false
      description: Returns a [paginated](#pagination) list of priorities. The list can contain all priorities or a subset determined by any combination of these criteria:<br><br> *  a list of priority IDs. Any invalid priority IDs are ignored.<br> *  a list of project IDs. Only priorities that are available in these projects will be returned. Any invalid project IDs are ignored.<br> *  whether the field configuration is a default. This returns priorities from company-managed (classic) projects only, as there is no concept of default priorities in team-managed projects.<br><br>**[Permissions](#permissions) required:** Permission to access Jira.
      operationId: atlassianSearchpriorities
      parameters:
      - description: The index of the first item to return in a page of results (page offset).
        in: query
        name: startAt
        schema:
          default: '0'
          type: string
      - description: The maximum number of items to return per page.
        in: query
        name: maxResults
        schema:
          default: '50'
          type: string
      - description: The list of priority IDs. To include multiple IDs, provide an ampersand-separated list. For example, `id=2&id=3`.
        in: query
        name: id
        schema:
          items:
            default: ''
            type: string
          type: array
      - description: The list of projects IDs. To include multiple IDs, provide an ampersand-separated list. For example, `projectId=10010&projectId=10111`.
        in: query
        name: projectId
        schema:
          items:
            default: ''
            type: string
          type: array
      - description: The name of priority to search for.
        in: query
        name: priorityName
        schema:
          default: ''
          type: string
      - description: Whether only the default priority is returned.
        in: query
        name: onlyDefault
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              example: '{"isLast":true,"maxResults":50,"startAt":0,"total":2,"values":[{"description":"Major loss of function.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/major.png","id":"1","isDefault":true,"name":"Major","self":"https://your-domain.atlassian.net/rest/api/3/priority/3","statusColor":"#009900"},{"description":"Very little impact.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/trivial.png","id":"2","isDefault":false,"name":"Trivial","self":"https://your-domain.atlassian.net/rest/api/3/priority/5","statusColor":"#cfcfcf"}]}'
              schema:
                $ref: '#/components/schemas/PageBeanPriority'
          description: Returned if the request is successful.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Search Priorities
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: READ
  /rest/api/3/priority/{id}:
    delete:
      deprecated: true
      description: '*Deprecated: please refer to the* [changelog](https://developer.atlassian.com/changelog/#CHANGE-1066) *for more details.*<br><br>Deletes an issue priority.<br><br>This operation is [asynchronous](#async). Follow the `location` link in the response to determine the status of the task and use [Get task](#api-rest-api-3-task-taskId-get) to obtain subsequent updates.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).'
      operationId: atlassianDeletepriority
      parameters:
      - description: The ID of the issue priority.
        in: path
        name: id
        required: true
        schema:
          type: string
      - description: The ID of the issue priority that will replace the currently selected resolution.
        in: query
        name: replaceWith
        required: true
        schema:
          type: string
      responses:
        '303':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskProgressBeanObject'
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The newPriority has to be provided."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request isn't valid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: '{"errorMessages":["You are not authorized to perform this action. Administrator privileges are required."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the user doesn't have the necessary permission.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["Priority with ID 10000 not found."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the issue priority isn't found.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if a task to delete the issue priority is already running.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Delete Priority
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-changes:
      - announced: '2023-07-18'
        details: https://developer.atlassian.com/changelog/#CHANGE-1066
        effective: '2023-12-01'
        type: removed
      x-experimental: true
      x-atlassian-connect-scope: ADMIN
    get:
      deprecated: false
      description: Returns an issue priority.<br><br>**[Permissions](#permissions) required:** Permission to access Jira.
      operationId: atlassianGetpriority
      parameters:
      - description: The ID of the issue priority.
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example: '{"description":"Major loss of function.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/major.png","id":"1","name":"Major","self":"https://your-domain.atlassian.net/rest/api/3/priority/3","statusColor":"#009900"}'
              schema:
                $ref: '#/components/schemas/Priority'
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect.
        '404':
          description: Returned if the issue priority isn't found.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      - {}
      summary: Atlassian Get Priority
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:priority:jira
        state: Beta
      x-atlassian-connect-scope: READ
    put:
      deprecated: false
      description: Updates an issue priority.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianUpdatepriority
      parameters:
      - description: The ID of the issue priority.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              description: My updated priority description
              iconUrl: images/icons/priorities/minor.png
              name: My updated priority
              statusColor: '#123456'
            schema:
              $ref: '#/components/schemas/UpdatePriorityDetails'
        required: true
      responses:
        '204':
          content:
            application/json:
              schema: {}
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The length of the description must not exceed 255 characters."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request isn't valid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: '{"errorMessages":["You are not authorized to perform this action. Administrator privileges are required."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the user doesn't have the necessary permission.
        '404':
          content:
            application/json:
              example: '{"errorMessages":["Priority with ID 10000 not found."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the issue priority isn't found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Update Priority
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: ADMIN
  /rest/api/3/priority:
    get:
      deprecated: true
      description: Returns the list of all issue priorities.<br><br>**[Permissions](#permissions) required:** Permission to access Jira.
      operationId: atlassianGetpriorities
      parameters: []
      responses:
        '200':
          content:
            application/json:
              example: '[{"description":"Major loss of function.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/major.png","id":"1","name":"Major","self":"https://your-domain.atlassian.net/rest/api/3/priority/3","statusColor":"#009900"},{"description":"Very little impact.","iconUrl":"https://your-domain.atlassian.net/images/icons/priorities/trivial.png","id":"2","name":"Trivial","self":"https://your-domain.atlassian.net/rest/api/3/priority/5","statusColor":"#cfcfcf"}]'
              schema:
                items:
                  $ref: '#/components/schemas/Priority'
                type: array
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      - {}
      summary: Atlassian Get Priorities
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:priority:jira
        state: Beta
      x-changes:
      - announced: '2022-10-11'
        details: https://developer.atlassian.com/cloud/jira/platform/changelog/#CHANGE-762
        effective: '2023-04-11'
        type: removed
      x-atlassian-connect-scope: READ
    post:
      deprecated: false
      description: Creates an issue priority.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianCreatepriority
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              description: My priority description
              iconUrl: images/icons/priorities/major.png
              name: My new priority
              statusColor: '#ABCDEF'
            schema:
              $ref: '#/components/schemas/CreatePriorityDetails'
        required: true
      responses:
        '201':
          content:
            application/json:
              example: '{"id":"10001"}'
              schema:
                $ref: '#/components/schemas/PriorityId'
          description: Returned if the request is successful.
        '400':
          content:
            application/json:
              example: '{"errorMessages":["The length of the description must not exceed 255 characters."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the request isn't valid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          content:
            application/json:
              example: '{"errorMessages":["Only Jira administrators can access issue type screen schemes."],"errors":{}}'
              schema:
                $ref: '#/components/schemas/ErrorCollection'
          description: Returned if the user doesn't have the necessary permission.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-configuration
      summary: Atlassian Create Priority
      tags:
      - Issue Priorities
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-experimental: true
      x-atlassian-connect-scope: ADMIN
components:
  schemas:
    Priority:
      additionalProperties: true
      description: An issue priority.
      properties:
        description:
          description: The description of the issue priority.
          type: string
        iconUrl:
          description: The URL of the icon for the issue priority.
          type: string
        id:
          description: The ID of the issue priority.
          type: string
        isDefault:
          description: Whether this priority is the default.
          type: boolean
        name:
          description: The name of the issue priority.
          type: string
        self:
          description: The URL of the issue priority.
          type: string
        statusColor:
          description: The color used to indicate the issue priority.
          type: string
      type: object
    UpdatePriorityDetails:
      additionalProperties: true
      description: Details of an issue priority.
      properties:
        description:
          description: The description of the priority.
          maxLength: 255
          type: string
          writeOnly: true
        iconUrl:
          description: The URL of an icon for the priority. Accepted protocols are HTTP and HTTPS. Built in icons can also be used.
          enum:
          - /images/icons/priorities/blocker.png
          - /images/icons/priorities/critical.png
          - /images/icons/priorities/high.png
          - /images/icons/priorities/highest.png
          - /images/icons/priorities/low.png
          - /images/icons/priorities/lowest.png
          - /images/icons/priorities/major.png
          - /images/icons/priorities/medium.png
          - /images/icons/priorities/minor.png
          - /images/icons/priorities/trivial.png
          maxLength: 255
          type: string
          writeOnly: true
        name:
          description: The name of the priority. Must be unique.
          maxLength: 60
          type: string
          writeOnly: true
        statusColor:
          description: The status color of the priority in 3-digit or 6-digit hexadecimal format.
          type: string
          writeOnly: true
      type: object
    PriorityId:
      additionalProperties: true
      description: The ID of an issue priority.
      properties:
        id:
          description: The ID of the issue priority.
          readOnly: true
          type: string
      required:
      - id
      type: object
    PageBeanPriority:
      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/Priority'
          readOnly: true
          type: array
      type: object
    TaskProgressBeanObject:
      additionalProperties: false
      description: Details about a task.
      properties:
        description:
          description: The description of the task.
          type: string
        elapsedRuntime:
          description: The execution time of the task, in milliseconds.
          format: int64
          type: integer
        finished:
          description: A timestamp recording when the task was finished.
          format: int64
          type: integer
        id:
          description: The ID of the task.
          type: string
        lastUpdate:
          description: A timestamp recording when the task progress was last updated.
          format: int64
          type: integer
        message:
          description: Information about the progress of the task.
          type: string
        progress:
          description: The progress of the task, as a percentage complete.
          format: int64
          type: integer
        result:
          description: The result of the task execution.
        self:
          description: The URL of the task.
          format: uri
          type: string
        started:
          description: A timestamp recording when the task was started.
          format: int64
          type: integer
        status:
          description: The status of the task.
          enum:
          - ENQUEUED
          - RUNNING
          - COMPLETE
          - FAILED
          - CANCEL_REQUESTED
          - CANCELLED
          - DEAD
          type: string
        submitted:
          description: A timestamp recording when the task was submitted.
          format: int64
          type: integer
        submittedBy:
          description: The ID of the user who submitted the task.
          format: int64
          type: integer
      required:
      - elapsedRuntime
      - id
      - lastUpdate
      - progress
      - self
      - status
      - submitted
      - submittedBy
      type: object
    ReorderIssuePriorities:
      additionalProperties: false
      description: Change the order of issue priorities.
      properties:
        after:
          description: The ID of the priority. Required if `position` isn't provided.
          type: string
          writeOnly: true
        ids:
          description: The list of issue IDs to be reordered. Cannot contain duplicates nor after ID.
          items:
            type: string
            writeOnly: true
          type: array
          writeOnly: true
        position:
          description: The position for issue priorities to be moved to. Required if `after` isn't provided.
          type: string
          writeOnly: true
      required:
      - ids
      type: object
    SetDefaultPriorityRequest:
      additionalProperties: false
      description: The new default issue priority.
      properties:
        id:
          description: The ID of the new default issue priority. Must be an existing ID or null. Setting this to null erases the default priority setting.
          type: string
          writeOnly: true
      required:
      - id
      type: object
    ErrorCollection:
      additionalProperties: false
      description: Error messages from an operation.
      properties:
        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
        status:
          format: int32
          type: integer
      type: object
    CreatePriorityDetails:
      additionalProperties: true
      description: Details of an issue priority.
      properties:
        description:
          description: The description of the priority.
          maxLength: 255
          type: string
          writeOnly: true
        iconUrl:
          description: The URL of an icon for the priority. Accepted protocols are HTTP and HTTPS. Built in icons can also be used.
          enum:
          - /images/icons/priorities/blocker.png
          - /images/icons/priorities/critical.png
          - /images/icons/priorities/high.png
          - /images/icons/priorities/highest.png
          - /images/icons/priorities/low.png
          - /images/icons/priorities/lowest.png
          - /images/icons/priorities/major.png
          - /images/icons/priorities/medium.png
          - /images/icons/priorities/minor.png
          - /images/icons/priorities/trivial.png
          maxLength: 255
          type: string
          writeOnly: true
        name:
          description: The name of the priority. Must be unique.
          maxLength: 60
          type: string
          writeOnly: true
        statusColor:
          description: The status color of the priority in 3-digit or 6-digit hexadecimal format.
          type: string
          writeOnly: true
      required:
      - name
      - statusColor
      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/
Atlassian Issue Priorities API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
