Class ProjectVersionsService

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.

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions

Hierarchy

CommonHttpService
- ProjectVersionsService

Index

Constructors

constructor

Methods

Constructors

constructor

new ProjectVersionsService(getClientInstance): ProjectVersionsService
Internal
Create a new instance of the service.
Parameters
- getClientInstance: (() => CommonHttpClient)
  - - (): CommonHttpClient
    - Returns CommonHttpClient
Returns ProjectVersionsService
Inherited from CommonHttpService.constructor

Methods

createRelatedWork

createRelatedWork(params): Promise<VersionRelatedWork>
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.
Parameters
- params: {
  id: string;
  versionRelatedWork: VersionRelatedWork;
  }
  - id: string
  - versionRelatedWork: VersionRelatedWork
    Example
Returns Promise<VersionRelatedWork>
Returned if the request is successful.

example:
```
{
  "category": "Design",
  "relatedWorkId": "fabcdef6-7878-1234-beaf-43211234abcd",
  "title": "Design link",
  "url": "https://www.atlassian.com"
}
```
Path
POST /rest/api/3/version/{id}/relatedwork @scopes-current write:jira-work @scopes-beta write:issue:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-relatedwork-post

createVersion

createVersion(params): Promise<Version>
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.
Parameters
- params: {
  version: Version;
  }
  - version: Version
    Example
Returns Promise<Version>
Returned if the request is successful.

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"
}
```
Path
POST /rest/api/3/version @scopes-current manage:jira-project @scopes-beta write:project-version:jira, read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-post

deleteAndReplaceVersion

deleteAndReplaceVersion(params): Promise<void>
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.
Parameters
- params: {
  deleteAndReplaceVersionBean: DeleteAndReplaceVersionBean;
  id: string;
  }
  - deleteAndReplaceVersionBean: DeleteAndReplaceVersionBean
  - id: string
    The ID of the version.
Returns Promise<void>
Returned if the version is deleted.

Path
POST /rest/api/3/version/{id}/removeAndSwap @scopes-current manage:jira-project @scopes-beta delete:project-version:jira, write:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-removeandswap-post

deleteRelatedWork

deleteRelatedWork(params): Promise<void>
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.
Parameters
- params: {
  relatedWorkId: string;
  versionId: string;
  }
  - relatedWorkId: string
    The ID of the related work to delete.
  - versionId: string
    The ID of the version that the target related work belongs to.
Returns Promise<void>
Path
DELETE /rest/api/3/version/{versionId}/relatedwork/{relatedWorkId} @scopes-current write:jira-work @scopes-beta write:issue:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-versionid-relatedwork-relatedworkid-delete

deleteVersion

deleteVersion(params): Promise<void>
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.
Parameters
- params: {
      id: string;
      moveAffectedIssuesTo?: string;
      moveFixIssuesTo?: string;
  }
  - id: string
    The ID of the version.
  - OptionalmoveAffectedIssuesTo?: string
    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.
  - OptionalmoveFixIssuesTo?: string
    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.
Returns Promise<void>
Deprecated
Path
DELETE /rest/api/3/version/{id} @scopes-current manage:jira-project @scopes-beta delete:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-delete

getProjectVersions

getProjectVersions(params): Promise<Version[]>

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.

Parameters

params: {
expand?: string;
projectIdOrKey: string;
}
- Optionalexpand?: string
  Use expand to include additional information in the response. This parameter accepts operations, which returns actions that can be performed on the version.
- projectIdOrKey: string
  The project ID or project key (case sensitive).

Returns Promise<Version[]>

Returned if the request is successful.

example:

[
  {
    "archived": false,
    "description": "An excellent version",
    "id": "10000",
    "name": "New Version 1",
    "overdue": true,
    "projectId": 10000,
    "releaseDate": 1278385482288,
    "releaseDateSet": true,
    "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
  }
]

Path

GET /rest/api/3/project/{projectIdOrKey}/versions @scopes-current read:jira-work @scopes-beta read:project-version:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-project-projectidorkey-versions-get

getProjectVersionsPaginated

getProjectVersionsPaginated(params): Promise<PageBeanVersion>
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.
Parameters
- params: {
      expand?: string;
      maxResults?: number;
      orderBy?:
          | "name"
          | "description"
          | "sequence"
          | "releaseDate"
          | "startDate"
          | "-description"
          | "+description"
          | "-name"
          | "+name"
          | "-releaseDate"
          | "+releaseDate"
          | "-sequence"
          | "+sequence"
          | "-startDate"
          | "+startDate";
      projectIdOrKey: string;
      query?: string;
      startAt?: number;
      status?: string;
  }
  - Optionalexpand?: string
    Use expand to include additional information in the response. This parameter accepts a comma-separated list. Expand options include:
    
    issuesstatus Returns the number of issues in each status category for each version.
    
    operations Returns actions that can be performed on the specified version.
    
    driver Returns the Atlassian account ID of the version driver.
    
    approvers Returns a list containing the approvers for this version.
  - OptionalmaxResults?: number
    The maximum number of items to return per page.
  - OptionalorderBy?:
        | "name"
        | "description"
        | "sequence"
        | "releaseDate"
        | "startDate"
        | "-description"
        | "+description"
        | "-name"
        | "+name"
        | "-releaseDate"
        | "+releaseDate"
        | "-sequence"
        | "+sequence"
        | "-startDate"
        | "+startDate"
    Order the results by a field:
    
    description Sorts by version description.
    
    name Sorts by version name.
    
    releaseDate Sorts by release date, starting with the oldest date. Versions with no release date are listed last.
    
    sequence Sorts by the order of appearance in the user interface.
    
    startDate Sorts by start date, starting with the oldest date. Versions with no start date are listed last.
  - projectIdOrKey: string
    The project ID or project key (case sensitive).
  - Optionalquery?: string
    Filter the results using a literal string. Versions with matching name or description are returned (case insensitive).
  - OptionalstartAt?: number
    The index of the first item to return in a page of results (page offset).
  - Optionalstatus?: string
    A list of status values used to filter the results by version status. This parameter accepts a comma-separated list. The status values are released, unreleased, and archived.
Returns Promise<PageBeanVersion>
Returned if the request is successful.

example:
```
{
  "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"
    }
  ]
}
```
Path
GET /rest/api/3/project/{projectIdOrKey}/version @scopes-current read:jira-work @scopes-beta read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-project-projectidorkey-version-get

getRelatedWork

getRelatedWork(params): Promise<VersionRelatedWork[]>

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.

Parameters

params: {
id: string;
}
- id: string
  The ID of the version.

Returns Promise<VersionRelatedWork[]>

Returned if the request is successful.

example:

[
  {
    "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"
  }
]

Path

GET /rest/api/3/version/{id}/relatedwork @scopes-current read:jira-work @scopes-beta read:project-version:jira

See

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-relatedwork-get

getVersion

getVersion(params): Promise<Version>
Returns a project version.

This operation can be accessed anonymously.

Permissions required: Browse projects project permission for the project containing the version.
Parameters
- params: {
  expand?: string;
  id: string;
  }
  - Optionalexpand?: string
    Use expand 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.
  - id: string
    The ID of the version.
Returns Promise<Version>
Returned if the request is successful.

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"
}
```
Path
GET /rest/api/3/version/{id} @scopes-current read:jira-work @scopes-beta read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-get

getVersionRelatedIssues

getVersionRelatedIssues(params): Promise<VersionIssueCounts>
Returns the following counts for a version:
- Number of issues where the fixVersion is set to the version.
- Number of issues where the affectedVersion is set to the version.
- Number of issues where a version custom field is set to the version.
This operation can be accessed anonymously.

Permissions required: Browse projects project permission for the project that contains the version.
Parameters
- params: {
  id: string;
  }
  - id: string
    The ID of the version.
Returns Promise<VersionIssueCounts>
Returned if the request is successful.

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"
}
```
Path
GET /rest/api/3/version/{id}/relatedIssueCounts @scopes-current read:jira-work @scopes-beta read:field:jira, read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-relatedissuecounts-get

getVersionUnresolvedIssues

getVersionUnresolvedIssues(params): Promise<VersionUnresolvedIssuesCount>
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.
Parameters
- params: {
  id: string;
  }
  - id: string
    The ID of the version.
Returns Promise<VersionUnresolvedIssuesCount>
Returned if the request is successful.

example:
```
{
  "issuesCount": 30,
  "issuesUnresolvedCount": 23,
  "self": "https://your-domain.atlassian.net/rest/api/3/version/10000"
}
```
Path
GET /rest/api/3/version/{id}/unresolvedIssueCount @scopes-current read:jira-work @scopes-beta read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-unresolvedissuecount-get

mergeVersions

mergeVersions(params): Promise<void>
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.
Parameters
- params: {
  id: string;
  moveIssuesTo: string;
  }
  - id: string
    The ID of the version to delete.
  - moveIssuesTo: string
    The ID of the version to merge into.
Returns Promise<void>
Returned if the version is deleted.

Path
PUT /rest/api/3/version/{id}/mergeto/{moveIssuesTo} @scopes-current manage:jira-project @scopes-beta delete:project-version:jira, write:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-mergeto-moveissuesto-put

moveVersion

moveVersion(params): Promise<Version>
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.
Parameters
- params: {
  id: string;
  versionMoveBean: VersionMoveBean;
  }
  - id: string
    The ID of the version to be moved.
  - versionMoveBean: VersionMoveBean
    Example
Returns Promise<Version>
Returned if the request is successful.

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"
}
```
Path
POST /rest/api/3/version/{id}/move @scopes-current manage:jira-project @scopes-beta write:project-version:jira, read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-move-post

updateRelatedWork

updateRelatedWork(params): Promise<VersionRelatedWork>
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.
Parameters
- params: {
  id: string;
  versionRelatedWork: VersionRelatedWork;
  }
  - id: string
    The ID of the version to update the related work on. For the related work id, pass it to the input JSON.
  - versionRelatedWork: VersionRelatedWork
    Example
Returns Promise<VersionRelatedWork>
Returned if the request is successful together with updated related work.

example:
```
{
  "category": "Design",
  "relatedWorkId": "fabcdef6-7878-1234-beaf-43211234abcd",
  "title": "Design link",
  "url": "https://www.atlassian.com"
}
```
Path
PUT /rest/api/3/version/{id}/relatedwork @scopes-current write:jira-work @scopes-beta write:issue:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-relatedwork-put

updateVersion

updateVersion(params): Promise<Version>
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.
Parameters
- params: {
  id: string;
  version: Version;
  }
  - id: string
    The ID of the version.
  - version: Version
    Example
Returns Promise<Version>
Returned if the request is successful.

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"
}
```
Path
PUT /rest/api/3/version/{id} @scopes-current manage:jira-project @scopes-beta write:project-version:jira, read:project-version:jira

See
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions#api-rest-api-3-version-id-put

`Protected` `Static`initialize

initialize(): void
Method to initialize the class. Normally used to set up validation rules.

Returns void
Overrides CommonHttpService.initialize

Class ProjectVersionsService

See

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CommonHttpClient

Returns ProjectVersionsService

Methods

createRelatedWork

Parameters

id: string

versionRelatedWork: VersionRelatedWork

Example

Returns Promise<VersionRelatedWork>

Path

See

createVersion

Parameters

version: Version

Example

Returns Promise<Version>

Path

See

deleteAndReplaceVersion

Parameters

deleteAndReplaceVersionBean: DeleteAndReplaceVersionBean

id: string

Returns Promise<void>

Path

See

deleteRelatedWork

Parameters

relatedWorkId: string

versionId: string

Returns Promise<void>

Path

See

deleteVersion

Parameters

id: string

OptionalmoveAffectedIssuesTo?: string

OptionalmoveFixIssuesTo?: string

Returns Promise<void>

Deprecated

Path

See

getProjectVersions

Parameters

Optionalexpand?: string

projectIdOrKey: string

Returns Promise<Version[]>

Path

See

getProjectVersionsPaginated

Parameters

Optionalexpand?: string

OptionalmaxResults?: number

OptionalorderBy?: | "name" | "description" | "sequence" | "releaseDate" | "startDate" | "-description" | "+description" | "-name" | "+name" | "-releaseDate" | "+releaseDate" | "-sequence" | "+sequence" | "-startDate" | "+startDate"

projectIdOrKey: string

Optionalquery?: string

OptionalstartAt?: number

Optionalstatus?: string

Returns Promise<PageBeanVersion>

Path

See

getRelatedWork

Parameters

id: string

Returns Promise<VersionRelatedWork[]>

Path

See

getVersion

Parameters

Optionalexpand?: string

id: string

Returns Promise<Version>

`Optional`moveAffectedIssuesTo?: string

`Optional`moveFixIssuesTo?: string

`Optional`expand?: string

`Optional`expand?: string

`Optional`maxResults?: number

`Optional`orderBy?:
| "name"
| "description"
| "sequence"
| "releaseDate"
| "startDate"
| "-description"
| "+description"
| "-name"
| "+name"
| "-releaseDate"
| "+releaseDate"
| "-sequence"
| "+sequence"
| "-startDate"
| "+startDate"

`Optional`query?: string

`Optional`startAt?: number

`Optional`status?: string

`Optional`expand?: string

`Protected` `Static`initialize