---
title: "Rank epics"
method: PUT
path: "/rest/agile/1.0/epic/{epicIdOrKey}/rank"
tags: ["Epic"]
---

# Rank epics

`PUT /rest/agile/1.0/epic/{epicIdOrKey}/rank`

## Request

- Base URL: `https://your-domain.atlassian.net`
- URL: `https://your-domain.atlassian.net/rest/agile/1.0/epic/{epicIdOrKey}/rank`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `https://auth.atlassian.com/authorize`
    - Token URL: `https://auth.atlassian.com/oauth/token` scopes: `write:epic:jira-software`

Moves (ranks) an epic before or after a given epic.

If rankCustomFieldId is not defined, the default rank field will be used.

**Note:** This operation does not work for epics in next-gen projects.

## Path parameters

- `epicIdOrKey` string, required

## Request body

- object
  - `rankAfterEpic` string
  - `rankBeforeEpic` string
  - `rankCustomFieldId` integer

## Response `204`

Empty response is returned if operation was successful.

## Other responses

- `400`: Returned if the request is invalid.
- `401`: Returned if the user is not logged in.
- `403`: Returned if the user does not have a valid license or does not have permission to rank. To rank issues user has to have schedule issue permission for epics that they want to rank.
- `404`: Returned when the given epics in the path parameter or the request body do not exist.

## Changes

- **2026-07-13** `4e108d54b990`: 1 info
  - the endpoint scheme security `basicAuth` was added to the API
- **2022-09-25** `ac057c9cf7e5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/atlassian/apis/jira-software-cloud-api/changes/rest/agile/1.0/epic/:epicIdOrKey/rank/put.md)

---

[API](https://skmtc.dev/atlassian/apis/jira-software-cloud-api.md) - [All operations](https://skmtc.dev/atlassian/apis/jira-software-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/atlassian/apis/jira-software-cloud-api/revisions/4e108d54b990?raw)