---
title: "Create priority scheme"
method: POST
path: "/rest/api/3/priorityscheme"
tags: ["Priority schemes"]
---

# Create priority scheme

`POST /rest/api/3/priorityscheme`

Creates a new priority scheme.

**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).

## Request body

- CreatePrioritySchemeDetails — Details of a new priority scheme
  - `defaultPriorityId` integer, required — The ID of the default priority for the priority scheme.
  - `description` string — The description of the priority scheme.
  - `mappings` PriorityMapping — Mapping of issue priorities for changes in priority schemes.
    - `in` object — The mapping of priorities for issues being migrated **into** this priority scheme. Key is the old priority ID, value is the new priority ID (must exist in this priority scheme). E.g. The current priority scheme has priority ID `10001`. Issues with priority ID `10000` are being migrated into this priority scheme will need mapping to new priorities. The `in` mapping would be `{"10000": 10001}`.
    - `out` object — The mapping of priorities for issues being migrated **out of** this priority scheme. Key is the old priority ID (must exist in this priority scheme), value is the new priority ID (must exist in the default priority scheme). Required for updating an existing priority scheme. Not used when creating a new priority scheme. E.g. The current priority scheme has priority ID `10001`. Issues with priority ID `10001` are being migrated out of this priority scheme will need mapping to new priorities. The `out` mapping would be `{"10001": 10000}`.
  - `name` string, required — The name of the priority scheme. Must be unique.
  - `priorityIds` integer[], required — The IDs of priorities in the scheme.
  - `projectIds` integer[] — The IDs of projects that will use the priority scheme.

## Response `201`

Returned if the request is completed.

- PrioritySchemeId — The ID of a priority scheme.
  - `id` string — The ID of the priority scheme.
  - `task` TaskProgressBeanJsonNode — Details about a task.
    - `description` string — The description of the task.
    - `elapsedRuntime` integer, required — The execution time of the task, in milliseconds.
    - `finished` integer — A timestamp recording when the task was finished.
    - `id` string, required — The ID of the task.
    - `lastUpdate` integer, required — A timestamp recording when the task progress was last updated.
    - `message` string — Information about the progress of the task.
    - `progress` integer, required — The progress of the task, as a percentage complete.
    - `result` JsonNode
      - `array` boolean
      - `bigDecimal` boolean
      - `bigInteger` boolean
      - `bigIntegerValue` integer
      - `binary` boolean
      - `binaryValue` string[]
      - `boolean` boolean
      - `booleanValue` boolean
      - `containerNode` boolean
      - `decimalValue` number
      - `double` boolean
      - `doubleValue` number, double
      - `elements` object
      - `fieldNames` object
      - `fields` object
      - `floatingPointNumber` boolean
      - `int` boolean
      - `intValue` integer
      - `integralNumber` boolean
      - `long` boolean
      - `longValue` integer
      - `missingNode` boolean
      - `null` boolean
      - `number` boolean
      - `numberType` 'INT' | 'LONG' | 'BIG_INTEGER' | 'FLOAT' | 'DOUBLE' | 'BIG_DECIMAL'
      - `numberValue` number
      - `object` boolean
      - `pojo` boolean
      - `textValue` string
      - `textual` boolean
      - `valueAsBoolean` boolean
      - `valueAsDouble` number, double
      - `valueAsInt` integer
      - `valueAsLong` integer
      - `valueAsText` string
      - `valueNode` boolean
    - `self` string, uri, required — The URL of the task.
    - `started` integer — A timestamp recording when the task was started.
    - `status` 'ENQUEUED' | 'RUNNING' | 'COMPLETE' | 'FAILED' | 'CANCEL_REQUESTED' | 'CANCELLED' | 'DEAD', required — The status of the task.
    - `submitted` integer, required — A timestamp recording when the task was submitted.
    - `submittedBy` integer, required — The ID of the user who submitted the task.

## Other responses

- `202` — Returned if the request is accepted.
- `400` — Returned if the request isn't valid. **Mappings Validation Errors** * ``The priorities with IDs [ID 1, ID 2, ...] require mapping. Please provide mappings in the 'in' mappings object, where these priorities are the keys with corresponding values.`` The listed priority ID(s) have not been provided as keys for ``in`` mappings but are required, add them to the mappings object.
- `401` — Returned if the authentication credentials are incorrect.
- `403` — Returned if the user doesn't have the necessary permissions.
- `409` — Returned if an action with this priority scheme is still in progress.

---

[API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/5a51740d7ab3/schema)