Update version
update_versionUpdate a version's name, dates, description, status, or sharing in OpenProject. Validate changes before applying, with support for moving sprint dates or closing releases.
Instructions
Change a version's name, dates, description, status or sharing.
Use it to move a sprint's dates, to close a finished release (status='closed'),
or to widen sharing so a subproject can use the version. The change is validated
through POST /versions/{id}/form first, so rejected values come back as
violations naming the attribute.
Only the parameters you pass are sent, so concurrent edits to other fields survive.
Versions carry no lockVersion upstream, so there is nothing to echo and no lock
parameter here — a 409 would mean the resource itself changed, not a stale version.
Returns the updated version in the same shape as create_version.
Pitfalls: end_date writes the API's endDate — it lands, unlike in the old
server. description REPLACES the stored text. Closing a version does not move or
unassign its work packages; they keep pointing at it. The defining project cannot be
changed — create a new version instead.
Cross-references: list_versions for ids and current values; delete_version
when the version must really disappear; update_work_package(version=...) to move
individual work packages between versions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name. Omit to leave it alone. | |
| status | No | open, locked or closed. Closing a version keeps its work packages but stops new ones being assigned — it is the safe alternative to delete_version. Omit to leave the status alone. | |
| sharing | No | none, descendants, hierarchy, tree or system. Narrowing the sharing of a version other projects already use is rejected by the API. Omit to leave it alone. | |
| end_date | No | New finish date, ISO YYYY-MM-DD, written to the API's 'endDate'. Pass null to clear it. Omit the parameter to leave it untouched. | __unchanged__ |
| start_date | No | New start date, ISO YYYY-MM-DD. Pass null to clear it. Omit the parameter entirely (the default) to leave it untouched. | __unchanged__ |
| version_id | Yes | Numeric version id from list_versions or get_project_metadata(project_id=...).versions. | |
| description | No | New markdown description; REPLACES the existing text. Pass null or an empty string to clear it. Omit to leave it untouched. | __unchanged__ |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Version id — what update_version, delete_version and the work-package 'version' field consume. | |
| name | No | Version name, e.g. 'Sprint 12' or '2.1'. | |
| source | No | 'sprint' when the row came from the backlogs sprints endpoint, 'version' otherwise. Sprints ARE versions upstream, so a row can be both and is then reported as 'sprint'. | version |
| status | No | open, locked or closed. Locked and closed versions reject new work package assignments. | |
| project | No | The project that DEFINES the version. A version shared from a parent project shows that parent here, not the project you asked about. | |
| sharing | No | How far the version is shared: none, descendants, hierarchy, tree, system. | |
| end_date | No | ISO date (YYYY-MM-DD); the version's finish date. | |
| created_at | No | ISO 8601 UTC timestamp. | |
| start_date | No | ISO date (YYYY-MM-DD). | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| description | No | Description as markdown (raw); html is dropped. |