Atlassian Jira Version API
The Atlassian Jira Version API enables managing project versions and releases within Jira.
OpenAPI Specification
components:
schemas:
Version:
additionalProperties: false
description: Details about a project version.
properties:
approvers:
description: >-
If the expand option `approvers` is used, returns a list containing
the approvers for this version.
items:
$ref: '#/components/schemas/VersionApprover'
readOnly: true
type: array
archived:
description: >-
Indicates that the version is archived. Optional when creating or
updating a version.
type: boolean
description:
description: >-
The description of the version. Optional when creating or updating a
version. The maximum size is 16,384 bytes.
type: string
driver:
description: >-
If the expand option `driver` is used, returns the Atlassian account
ID of the driver.
readOnly: true
type: string
expand:
description: >-
Use [expand](em>#expansion) to include additional information about
version in the response. This parameter accepts a comma-separated
list. Expand options include:
* `operations` Returns the list of operations available for this version.
* `issuesstatus` Returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property contains a count of issues with a status other than *to do*, *in progress*, and *done*.
* `driver` Returns the Atlassian account ID of the version driver.
* `approvers` Returns a list containing approvers for this version.
Optional for create and update.
type: string
xml:
attribute: true
id:
description: The ID of the version.
readOnly: true
type: string
issuesStatusForFixVersion:
allOf:
- $ref: '#/components/schemas/VersionIssuesStatus'
description: >-
If the expand option `issuesstatus` is used, returns the count of
issues in this version for each of the status categories *to do*,
*in progress*, *done*, and *unmapped*. The *unmapped* property
contains a count of issues with a status other than *to do*, *in
progress*, and *done*.
readOnly: true
moveUnfixedIssuesTo:
description: >-
The URL of the self link to the version to which all unfixed issues
are moved when a version is released. Not applicable when creating a
version. Optional when updating a version.
format: uri
type: string
name:
description: >-
The unique name of the version. Required when creating a version.
Optional when updating a version. The maximum length is 255
characters.
type: string
operations:
description: >-
If the expand option `operations` is used, returns the list of
operations available for this version.
items:
$ref: '#/components/schemas/SimpleLink'
readOnly: true
type: array
overdue:
description: Indicates that the version is overdue.
readOnly: true
type: boolean
project:
description: Deprecated. Use `projectId`.
type: string
projectId:
description: >-
The ID of the project to which this version is attached. Required
when creating a version. Not applicable when updating a version.
format: int64
type: integer
releaseDate:
description: >-
The release date of the version. Expressed in ISO 8601 format
(yyyy-mm-dd). Optional when creating or updating a version.
format: date
type: string
released:
description: >-
Indicates that the version is released. If the version is released a
request to release again is ignored. Not applicable when creating a
version. Optional when updating a version.
type: boolean
self:
description: The URL of the version.
format: uri
readOnly: true
type: string
startDate:
description: >-
The start date of the version. Expressed in ISO 8601 format
(yyyy-mm-dd). Optional when creating or updating a version.
format: date
type: string
userReleaseDate:
description: >-
The date on which work on this version is expected to finish,
expressed in the instance's *Day/Month/Year Format* date format.
readOnly: true
type: string
userStartDate:
description: >-
The date on which work on this version is expected to start,
expressed in the instance's *Day/Month/Year Format* date format.
readOnly: true
type: string
type: object
xml:
name: version
VersionIssueCounts:
additionalProperties: false
description: Various counts of issues within a version.
properties:
customFieldUsage:
description: List of custom fields using the version.
items:
$ref: '#/components/schemas/VersionUsageInCustomField'
readOnly: true
type: array
issueCountWithCustomFieldsShowingVersion:
description: Count of issues where a version custom field is set to the version.
format: int64
readOnly: true
type: integer
issuesAffectedCount:
description: Count of issues where the `affectedVersion` is set to the version.
format: int64
readOnly: true
type: integer
issuesFixedCount:
description: Count of issues where the `fixVersion` is set to the version.
format: int64
readOnly: true
type: integer
self:
description: The URL of these count details.
format: uri
readOnly: true
type: string
type: object
xml:
name: version
VersionRelatedWork:
additionalProperties: false
description: Associated related work to a version
properties:
category:
description: The category of the related work
readOnly: true
type: string
issueId:
description: The title of the related work
format: int64
readOnly: true
type: integer
relatedWorkId:
description: >-
The id of the related work. For the native release note related work
item, this will be null, and Rest API does not support updating it.
readOnly: true
type: string
title:
description: The title of the related work
readOnly: true
type: string
url:
description: The URL of the related work
format: uri
readOnly: true
type: string
required:
- category
type: object
VersionUnresolvedIssuesCount:
additionalProperties: false
description: Count of a version's unresolved issues.
properties:
issuesCount:
description: Count of issues.
format: int64
readOnly: true
type: integer
issuesUnresolvedCount:
description: Count of unresolved issues.
format: int64
readOnly: true
type: integer
self:
description: The URL of these count details.
format: uri
readOnly: true
type: string
type: object
xml:
name: version
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/version/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/version/{id}:
delete:
deprecated: true
description: >-
Deletes a project version.<br><br>Deprecated, use [ Delete and replace
version](#api-rest-api-3-version-id-removeAndSwap-post) that supports
swapping version values in custom fields, in addition to the swapping
for `fixVersion` and `affectedVersion` provided in this
resource.<br><br>Alternative versions can be provided to update issues
that use the deleted version in `fixVersion` or `affectedVersion`. If
alternatives are not provided, occurrences of `fixVersion` and
`affectedVersion` that contain the deleted version are
cleared.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) or *Administer
Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
that contains the version.
operationId: atlassianDeleteversion
parameters:
- description: The ID of the version.
in: path
name: id
required: true
schema:
type: string
- description: >-
The ID of the version to update `fixVersion` to when the field
contains the deleted version. The replacement version must be in the
same project as the version being deleted and cannot be the version
being deleted.
in: query
name: moveFixIssuesTo
schema:
type: string
- description: >-
The ID of the version to update `affectedVersion` to when the field
contains the deleted version. The replacement version must be in the
same project as the version being deleted and cannot be the version
being deleted.
in: query
name: moveAffectedIssuesTo
schema:
type: string
responses:
'204':
description: Returned if the version is deleted.
'400':
description: Returned if the request is invalid.
'401':
description: |-
Returned if:
* the authentication credentials are incorrect.
* the user does not have the required permissions.
'404':
description: Returned if the version is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Delete Version
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- delete:project-version:jira
state: Beta
x-atlassian-connect-scope: PROJECT_ADMIN
get:
deprecated: false
description: >-
Returns a project version.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** *Browse
projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
containing the version.
operationId: atlassianGetversion
parameters:
- description: The ID of the version.
in: path
name: id
required: true
schema:
type: string
- description: >-
Use [expand](#expansion) to include additional information about
version in the response. This parameter accepts a comma-separated
list. Expand options include:
* `operations` Returns the list of operations available for this version.
* `issuesstatus` Returns the count of issues in this version for each of the status categories *to do*, *in progress*, *done*, and *unmapped*. The *unmapped* property represents the number of issues with a status other than *to do*, *in progress*, and *done*.
* `driver` Returns the Atlassian account ID of the version driver.
* `approvers` Returns a list containing the Atlassian account IDs of approvers for this version.
in: query
name: expand
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"archived":false,"description":"An excellent
version","id":"10000","name":"New Version
1","overdue":true,"projectId":10000,"releaseDate":"2010-07-06","released":true,"self":"https://your-domain.atlassian.net/rest/api/3/version/10000","userReleaseDate":"6/Jul/2010"}
schema:
$ref: '#/components/schemas/Version'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the version is not found or the user does not have the
necessary permission.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Version
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:project-version:jira
state: Beta
x-atlassian-connect-scope: READ
put:
deprecated: false
description: >-
Updates a project version.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) or *Administer
Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
that contains the version.
operationId: atlassianUpdateversion
parameters:
- description: The ID of the version.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
archived: false
description: An excellent version
id: '10000'
name: New Version 1
overdue: true
projectId: 10000
releaseDate: '2010-07-06'
released: true
self: https://your-domain.atlassian.net/rest/api/~ver~/version/10000
userReleaseDate: 6/Jul/2010
schema:
$ref: '#/components/schemas/Version'
required: true
responses:
'200':
content:
application/json:
example: >-
{"archived":false,"description":"An excellent
version","id":"10000","name":"New Version
1","project":"PXA","projectId":10000,"releaseDate":"2010-07-06","released":true,"self":"https://your-domain.atlassian.net/rest/api/3/version/10000","userReleaseDate":"6/Jul/2010"}
schema:
$ref: '#/components/schemas/Version'
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* the request is invalid.
* the user does not have the required permissions.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: Returned if the version is not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Update Version
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- write:project-version:jira
- read:project-version:jira
state: Beta
x-atlassian-connect-scope: PROJECT_ADMIN
/rest/api/3/version/{id}/mergeto/{moveIssuesTo}:
put:
deprecated: false
description: >-
Merges two project versions. The merge is completed by deleting the
version specified in `id` and replacing any occurrences of its ID in
`fixVersion` with the version ID specified in
`moveIssuesTo`.<br><br>Consider using [ Delete and replace
version](#api-rest-api-3-version-id-removeAndSwap-post) instead. This
resource supports swapping version values in `fixVersion`,
`affectedVersion`, and custom fields.<br><br>This operation can be
accessed anonymously.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) or *Administer
Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
that contains the version.
operationId: atlassianMergeversions
parameters:
- description: The ID of the version to delete.
in: path
name: id
required: true
schema:
type: string
- description: The ID of the version to merge into.
in: path
name: moveIssuesTo
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the version is deleted.
'400':
description: Returned if the request is invalid.
'401':
description: |-
Returned if:
* the authentication credentials are incorrect or missing.
* the user does not have the required permissions.
'404':
description: >-
Returned if the version to be deleted or the version to merge to are
not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Merge Versions
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- delete:project-version:jira
- write:project-version:jira
state: Beta
x-atlassian-connect-scope: PROJECT_ADMIN
/rest/api/3/version/{id}/move:
post:
deprecated: false
description: >-
Modifies the version's sequence within the project, which affects the
display order of the versions in Jira.<br><br>This operation can be
accessed anonymously.<br><br>**[Permissions](#permissions) required:**
*Browse projects* project permission for the project that contains the
version.
operationId: atlassianMoveversion
parameters:
- description: The ID of the version to be moved.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
after: https://your-domain.atlassian.net/rest/api/~ver~/version/10000
schema:
$ref: '#/components/schemas/VersionMoveBean'
required: true
responses:
'200':
content:
application/json:
example: >-
{"archived":false,"description":"An excellent
version","id":"10000","name":"New Version
1","overdue":true,"projectId":10000,"releaseDate":"2010-07-06","released":true,"self":"https://your-domain.atlassian.net/rest/api/3/version/10000","userReleaseDate":"6/Jul/2010"}
schema:
$ref: '#/components/schemas/Version'
description: Returned if the request is successful.
'400':
description: |-
Returned if:
* no body parameters are provided.
* `after` and `position` are provided.
* `position` is invalid.
'401':
description: |-
Returned if:
* the authentication credentials are incorrect or missing
* the user does not have the required commissions.
'404':
description: Returned if the version or move after version are not found.
security:
- basicAuth: []
- OAuth2:
- manage:jira-project
- {}
summary: Atlassian Move Version
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- manage:jira-project
state: Current
- scheme: OAuth2
scopes:
- write:project-version:jira
- read:project-version:jira
state: Beta
x-atlassian-connect-scope: PROJECT_ADMIN
/rest/api/3/version/{id}/relatedIssueCounts:
get:
deprecated: false
description: >-
Returns the following counts for a version:<br><br> * Number of issues
where the `fixVersion` is set to the version.<br> * Number of issues
where the `affectedVersion` is set to the version.<br> * Number of
issues where a version custom field is set to the version.<br><br>This
operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** *Browse
projects* project permission for the project that contains the version.
operationId: atlassianGetversionrelatedissues
parameters:
- description: The ID of the version.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
{"customFieldUsage":[{"customFieldId":10000,"fieldName":"Field1","issueCountWithVersionInCustomField":2},{"customFieldId":10010,"fieldName":"Field2","issueCountWithVersionInCustomField":3}],"issueCountWithCustomFieldsShowingVersion":54,"issuesAffectedCount":101,"issuesFixedCount":23,"self":"https://your-domain.atlassian.net/rest/api/3/version/10000"}
schema:
$ref: '#/components/schemas/VersionIssueCounts'
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect.
'404':
description: |-
Returned if:
* the version is not found.
* the user does not have the required permissions.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Version S Related Issues Count
tags:
- Project Versions
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:field:jira
- read:project-version:jira
state: Beta
x-atlassian-connect-scope: READ
/rest/api/3/version/{id}/relatedwork:
get:
deprecated: false
description: >-
Returns related work items for the given version id.<br><br>This
operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** *Browse
projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
containing the version.
operationId: atlassianGetrelatedwork
parameters:
- description: The ID of the version.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example: >-
[{"category":"Design","issueId":10001,"relatedWorkId":"fabcdef6-7878-1234-beaf-43211234abcd","title":"Design
link","url":"https://www.atlassian.com"},{"category":"Communications","issueId":10002,"relatedWorkId":"fabcdef6-7878-1234-beaf-43211234abce","title":"Chat
application","url":"https://www.atlassian.com"},{"category":"External
Link","issueId":10003,"relatedWorkId":"fabcdef6-7878-1234-beaf-43211234abcf","title":"Some
website","url":"https://www.atlassian.com"}]
schema:
items:
$ref: '#/components/schemas/VersionRelatedWork'
type: array
description: Returned if the request is successful.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'404':
description: >-
Returned if the version is not found or the user does not have the
necessary permission.
'500':
description: Returned if reading related work fails
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Related Work
tags:
- Project Versions
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:project-version:jira
state: Beta
x-atlassian-connect-scope: READ
post:
deprecated: false
description: >-
Creates a related work for the given version. You can only create a
generic link type of related works via this API. relatedWorkId will be
auto-generated UUID, that does not need to be provided.<br><br>This
operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** *Resolve
issues:* and *Edit issues* [Managing project
permissions](https://confluence.atlassian.com/adminjiraserver/managing-project-permissions-938847145.html)
for the project that contains the version.
operationId: atlassianCreaterelatedwork
parameters:
- in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VersionRelatedWork'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/VersionRelatedWork'
description: Returned if the request is successful.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
'403':
description: Returned if the user does not have the required permissions.
'404':
description: Returned if the version is not found.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Create Related Work
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:issue:jira
state: Beta
x-atlassian-connect-scope: PROJECT_ADMIN
put:
deprecated: false
description: >-
Updates the given related work. You can only update generic link related
works via Rest APIs. Any archived version related works can't be
edited.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** *Resolve
issues:* and *Edit issues* [Managing project
permissions](https://confluence.atlassian.com/adminjiraserver/managing-project-permissions-938847145.html)
for the project that contains the version.
operationId: atlassianUpdaterelatedwork
parameters:
- description: >-
The ID of the version to update the related work on. For the related
work id, pass it to the input JSON.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/VersionRelatedWork'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VersionRelatedWork'
description: >-
Returned if the request is successful together with updated related
work.
'400':
description: Returned if the request data is invalid
'401':
description: Returned if the authentication credentials are incorrect.
'403':
description: Returned if the user does not have the required permissions.
'404':
description: Returned if the version or the related work is not found.
security:
- basicAuth: []
- OAuth2:
- write:jira-work
- {}
summary: Atlassian Update Related Work
tags:
- Project Versions
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- write:jira-work
state: Current
- scheme: OAuth2
scopes:
- write:issue:jira
state: Beta
x-atlassian-connect-scope: PROJECT_ADMIN
/rest/api/3/version/{id}/removeAndSwap:
post:
deprecated: false
description: >-
Deletes a project version.<br><br>Alternative versions can be provided
to update issues that use the deleted version in `fixVersion`,
`affectedVersion`, or any version picker custom fields. If alternatives
are not provided, occurrences of `fixVersion`, `affectedVersion`, and
any version picker custom field, that contain the deleted version, are
cleared. Any replacement version must be in the same project as the
version being deleted and cannot be the version being
deleted.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:**
*Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg) or *Administer
Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the project
that contains the version.
operationId: atlassianDeleteandreplaceversion
parameters:
- description: The ID of the version.
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAndReplaceVersionBean'
required: true
responses:
'204':
content:
application/json:
schema: {}
description: Returned if the version is deleted.
'400':
description: Returned if the request is invalid.
'401':
description: Returned if the authentication credentia
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-version--openapi-original.yml