This resource represents project versions. Use it to get, get lists of, create, update, move, merge, and delete project versions. This resource also provides counts of issues by version.
Returns a paginated list of all versions in a project. See the Get project versions resource if you want to get a full list of versions without pagination.
This operation can be accessed anonymously.
Permissions required: Browse Projects project permission for the project.
Connect app scope required: READ
read:jira-workread:project-version:jirastring
Requiredinteger
integer
string
string
string
string
Returned if the request is successful.
A page of items.
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/project/{projectIdOrKey}/version`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
"isLast": false,
"maxResults": 2,
"nextPage": "https://your-domain.atlassian.net/rest/api/3/project/PR/version?startAt=2&maxResults=2",
"self": "https://your-domain.atlassian.net/rest/api/3/project/PR/version?startAt=0&maxResults=2",
"startAt": 0,
"total": 7,
"values": [
{
"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"
},
{
"archived": false,
"description": "Minor Bugfix version",
"id": "10010",
"issuesStatusForFixVersion": {
"done": 100,
"inProgress": 20,
"toDo": 10,
"unmapped": 0
},
"name": "Next Version",
"overdue": false,
"projectId": 10000,
"released": false,
"self": "https://your-domain.atlassian.net/rest/api/3/version/10010"
}
]
}Returns all versions in a project. The response is not paginated. Use Get project versions paginated if you want to get the versions in a project with pagination.
This operation can be accessed anonymously.
Permissions required: Browse Projects project permission for the project.
Connect app scope required: READ
read:jira-workread:project-version:jirastring
Requiredstring
Returned if the request is successful.
array<Version>
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/project/{projectIdOrKey}/versions`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
[
{
"archived": false,
"description": "An excellent version",
"id": "10000",
"name": "New Version 1",
"overdue": true,
"projectId": 10000,
"releaseDate": 1278385482288,
"releaseDateSet": false,
"released": true,
"self": "https://your-domain.atlassian.net/rest/api/3/version/10000",
"startDateSet": false,
"userReleaseDate": "6/Jul/2010"
},
{
"archived": false,
"description": "Minor Bugfix version",
"id": "10010",
"issuesStatusForFixVersion": {
"done": 100,
"inProgress": 20,
"toDo": 10,
"unmapped": 0
},
"name": "Next Version",
"overdue": false,
"projectId": 10000,
"releaseDateSet": false,
"released": false,
"self": "https://your-domain.atlassian.net/rest/api/3/version/10010",
"startDateSet": false
}
]Creates a project version.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project the version is added to.
Connect app scope required: PROJECT_ADMIN
manage:jira-projectwrite:project-version:jira, read:project-version:jiraboolean
string
string
string
string
string
integer
string
boolean
string
Returned if the request is successful.
Details about a project version.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"archived": false,
"description": "An excellent version",
"name": "New Version 1",
"projectId": 10000,
"releaseDate": "2010-07-06",
"released": true
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/version`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
{
"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"
}Returns a project version.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project containing the version.
Connect app scope required: READ
read:jira-workread:project-version:jirastring
Requiredstring
Returned if the request is successful.
Details about a project version.
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
{
"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"
}Updates a project version.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
manage:jira-projectwrite:project-version:jira, read:project-version:jirastring
Requiredboolean
string
string
string
string
string
integer
string
boolean
string
Returned if the request is successful.
Details about a project version.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"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"
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}`, {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
{
"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"
}Deletes a project version.
Deprecated, use Delete and replace version that supports swapping version values in custom fields, in addition to the swapping for fixVersion and affectedVersion provided in this resource.
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.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
manage:jira-projectdelete:project-version:jirastring
Requiredstring
string
Returned if the version is deleted.
1
2
3
4
5
6
7
8
9
10
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}`, {
method: 'DELETE'
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());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.
Consider using Delete and replace version instead. This resource supports swapping version values in fixVersion, affectedVersion, and custom fields.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
manage:jira-projectdelete:project-version:jira, write:project-version:jirastring
Requiredstring
RequiredReturned if the version is deleted.
any
1
2
3
4
5
6
7
8
9
10
11
12
13
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/mergeto/{moveIssuesTo}`, {
method: 'PUT',
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());Modifies the version's sequence within the project, which affects the display order of the versions in Jira.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
manage:jira-projectwrite:project-version:jira, read:project-version:jirastring
Requiredstring
string
Returned if the request is successful.
Details about a project version.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"after": "https://your-domain.atlassian.net/rest/api/~ver~/version/10000"
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/move`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
{
"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"
}Returns the following counts for a version:
fixVersion is set to the version.affectedVersion is set to the version.This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project that contains the version.
Connect app scope required: READ
read:jira-workread:field:jira, read:project-version:jirastring
RequiredReturned if the request is successful.
Various counts of issues within a version.
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/relatedIssueCounts`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"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"
}Returns related work items for the given version id.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project containing the version.
Connect app scope required: READ
read:jira-workread:project-version:jirastring
RequiredReturned if the request is successful.
array<VersionRelatedWork>
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/relatedwork`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[
{
"category": "Design",
"issueId": 10001,
"relatedWorkId": "fabcdef6-7878-1234-beaf-43211234abcd",
"title": "Design link",
"url": "https://www.atlassian.com"
},
{
"category": "Communications",
"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",
"url": "https://www.atlassian.com"
}
]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.
This operation can be accessed anonymously.
Permissions required: Resolve issues: and Edit issues Managing project permissions for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
write:jira-workwrite:issue:jirastring
Requiredstring
Requiredstring
string
Returned if the request is successful together with updated related work.
Associated related work to a version
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"category": "Design",
"relatedWorkId": "fabcdef6-7878-1234-beaf-43211234abcd",
"title": "Design link",
"url": "https://www.atlassian.com"
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/relatedwork`, {
method: 'PUT',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
{
"category": "Design",
"relatedWorkId": "fabcdef6-7878-1234-beaf-43211234abcd",
"title": "Design link",
"url": "https://www.atlassian.com"
}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.
This operation can be accessed anonymously.
Permissions required: Resolve issues: and Edit issues Managing project permissions for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
write:jira-workwrite:issue:jirastring
Requiredstring
Requiredstring
string
Returned if the request is successful.
Associated related work to a version
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"category": "Design",
"title": "Design link",
"url": "https://www.atlassian.com"
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/relatedwork`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
6
{
"category": "Design",
"relatedWorkId": "fabcdef6-7878-1234-beaf-43211234abcd",
"title": "Design link",
"url": "https://www.atlassian.com"
}Deletes a project version.
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.
This operation can be accessed anonymously.
Permissions required: Administer Jira global permission or Administer Projects project permission for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
manage:jira-projectdelete:project-version:jira, write:project-version:jirastring
Requiredarray<CustomFieldReplacement>
integer
integer
Returned if the version is deleted.
any
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
var bodyData = `{
"customFieldReplacementList": [
{
"customFieldId": 66,
"moveTo": 67
}
],
"moveAffectedIssuesTo": 97,
"moveFixIssuesTo": 92
}`;
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/removeAndSwap`, {
method: 'POST',
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: bodyData
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());Returns counts of the issues and unresolved issues for the project version.
This operation can be accessed anonymously.
Permissions required: Browse projects project permission for the project that contains the version.
Connect app scope required: READ
read:jira-workread:project-version:jirastring
RequiredReturned if the request is successful.
Count of a version's unresolved issues.
1
2
3
4
5
6
7
8
9
10
11
12
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{id}/unresolvedIssueCount`, {
headers: {
'Accept': 'application/json'
}
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.json());1
2
3
4
5
{
"issuesCount": 30,
"issuesUnresolvedCount": 23,
"self": "https://your-domain.atlassian.net/rest/api/3/version/10000"
}Deletes the given related work for the given version.
This operation can be accessed anonymously.
Permissions required: Resolve issues: and Edit issues Managing project permissions for the project that contains the version.
Connect app scope required: PROJECT_ADMIN
write:jira-workwrite:issue:jirastring
Requiredstring
RequiredReturned if the related work is deleted.
1
2
3
4
5
6
7
8
9
10
// This sample uses Atlassian Forge
// https://developer.atlassian.com/platform/forge/
import api, { route } from "@forge/api";
const response = await api.asUser().requestJira(route`/rest/api/3/version/{versionId}/relatedwork/{relatedWorkId}`, {
method: 'DELETE'
});
console.log(`Response: ${response.status} ${response.statusText}`);
console.log(await response.text());Rate this page: