Create version
create_versionCreate a version (release, milestone, or sprint) in an OpenProject project to plan releases or start sprints before assigning work packages.
Instructions
Create a version (release, milestone or sprint) inside a project.
Use it to open a new sprint or plan a release before assigning work packages to it.
The call goes through POST /versions/form first, so a duplicate name or an
impossible date range comes back as violations naming the attribute instead of an
opaque rejection.
Returns the created version {id, name, project, status, start_date, end_date, description, sharing, source, created_at, updated_at}. The id is what
update_work_package(version=...) and update_version consume.
Pitfalls: end_date is the version's finish date and is written to the API's
endDate field — passing a date here always lands (an older client dropped it
silently). Creating versions needs the 'manage versions' permission in the project,
so a 403 is about the account, not the payload. Versions are per project: sharing is
the only way another project sees this one.
Cross-references: list_versions for what already exists (and for the ids);
update_version to change dates or close it later; list_projects for the
project id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Version name, e.g. 'Sprint 12' or 'Release 2.1'. Must be unique inside the defining project. | |
| status | No | open (default upstream), locked or closed. Locked and closed versions cannot receive new work packages, so create with 'open' unless you are recording history. | |
| sharing | No | Which other projects may use this version: none (default), descendants, hierarchy, tree or system (the whole instance). Use 'descendants' for a release shared with subprojects. | |
| end_date | No | ISO date (YYYY-MM-DD) the version finishes — this is the version's due date, sent as the API's 'endDate'. Omit for none. | |
| project_id | Yes | Numeric id or identifier of the project that will DEFINE the version. Sharing decides which other projects can use it; the defining project cannot be changed afterwards. | |
| start_date | No | ISO date (YYYY-MM-DD) the version starts. Omit for none. | |
| description | No | Markdown description of the version's scope. Omit for none. |
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. |