API: Versions
Work Packages can be assigned to a version. As such, versions serve to group Work Packages into logical units where each group comprises all the work packages that needs to be finished in order for the version to be finished.
Actions
| Link | Description | Condition |
|---|---|---|
| update | Form endpoint that aids in preparing and performing edits on the version | Permission: manage versions |
| updateImmediately | Directly perform edits on the version | Permission: manage versions |
Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| self | This version | Version | not null | READ |
| definingProject | The project to which the version belongs | Project | only present if the project is visible for the current user | READ |
| availableInProjects | Projects where this version can be used | Projects | not null | READ |
Depending on custom fields defined for versions, additional linked properties might exist.
Local Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| id | Version id | Integer | x > 0 | READ |
| name | Version name | String | not null, may not exceed 60 characters | READ / WRITE |
| description | Formattable | READ / WRITE | ||
| startDate | Date | READ / WRITE | ||
| endDate | Date | READ / WRITE | ||
| status | The current status of the version | String | not null, only ‘open’, ‘finished’, ‘closed’ | READ / WRITE |
| sharing | The current status of the version | String | not null, limited to fixed set as defined by form | READ / WRITE |
| createdAt | Time of creation | DateTime | not null | READ |
| updatedAt | Time of the most recent change to the version | DateTime | not null | READ |
Depending on custom fields defined for versions, additional properties might exist.
Methods
List versions available in a project
This endpoint lists the versions that are available in a given project. Note that due to sharing this might be more than the versions defined by that project.
id
integer
required path
ID of the project whose versions will be listed
Example:1
200
OK
{
"_embedded": {
"elements": [
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"self": {
"href": "/api/v3/versions/11"
}
},
"_type": "Version",
"description": {
"format": "plain",
"html": "This version has a description",
"raw": "This version has a description"
},
"endDate": null,
"id": 11,
"name": "v3.0 Alpha",
"startDate": "2014-11-20",
"status": "Open"
},
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/12/projects"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"self": {
"href": "/api/v3/versions/12"
}
},
"_type": "Version",
"description": {
"format": "plain",
"html": "",
"raw": ""
},
"endDate": null,
"id": 12,
"name": "v2.0",
"startDate": null,
"status": "Closed"
},
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/10/projects"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"self": {
"href": "/api/v3/versions/10"
}
},
"_type": "Version",
"description": {
"format": "plain",
"html": "",
"raw": ""
},
"endDate": null,
"id": 10,
"name": "v1.0",
"startDate": null,
"status": "Open"
}
]
},
"_links": {
"self": {
"href": "/api/v3/projects/11/versions"
}
},
"_type": "Collection",
"count": 3,
"total": 3
}
Versions_by_ProjectModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The versions collection\n\n**Resource**: VersionsCollection",
"readOnly": true
}
]
}
}
},
"_embedded": {
"type": "object",
"properties": {
"elements": {
"type": "array",
"readOnly": true,
"items": {
"allOf": [
{
"$ref": "#/components/schemas/VersionModel"
},
{
"description": "Collection of Versions"
}
]
}
}
}
}
}
}
]
}
404
Returned if the project does not exist or the client does not have sufficient permissions to see it.
Required permission: view work packages or manage versions (on given project)
Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
List versions
Returns a collection of versions. The client can choose to filter the versions similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain versions, for which the requesting client has sufficient permissions (view_work_packages).
filters
string
optional query
JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:
- sharing: filters versions by how they are shared within the server (none, descendants, hierarchy, tree, system).
Example:[{ "sharing": { "operator": "*", "values": ["system"] }" }]
sortBy
string
optional query
JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported attributes are:
- id: Sort by the version id
- name: Sort by the version name using numeric collation, comparing sequences of decimal digits by their numeric value
- semver_name: Deprecated, use name instead
Example:[["name", "desc"]]
200
OK
{
"_embedded": {
"elements": [
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
},
"definingProject": {
"href": "/api/v3/projects/12"
},
"self": {
"href": "/api/v3/versions/11"
}
},
"_type": "Version",
"description": {
"format": "plain",
"html": "This version has a description",
"raw": "This version has a description"
},
"endDate": null,
"id": 11,
"name": "v3.0 Alpha",
"startDate": "2014-11-20",
"status": "Open"
},
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/12/projects"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"self": {
"href": "/api/v3/versions/12"
}
},
"_type": "Version",
"description": {
"format": "plain",
"html": "",
"raw": ""
},
"endDate": null,
"id": 12,
"name": "v2.0",
"startDate": null,
"status": "Closed"
},
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/13/projects"
},
"definingProject": {
"href": "/api/v3/projects/13"
},
"self": {
"href": "/api/v3/versions/10"
}
},
"_type": "Version",
"description": {
"format": "plain",
"html": "",
"raw": ""
},
"endDate": null,
"id": 10,
"name": "v1.0",
"startDate": null,
"status": "Open"
}
]
},
"_links": {
"self": {
"href": "/api/v3/versions"
}
},
"_type": "Collection",
"count": 3,
"total": 3
}
VersionsModel{
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/versions"
}
},
"total": 3,
"count": 3,
"_type": "Collection",
"_embedded": {
"elements": [
{
"_links": {
"self": {
"href": "/api/v3/versions/11"
},
"definingProject": {
"href": "/api/v3/projects/12"
},
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
}
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "Open"
},
{
"_links": {
"self": {
"href": "/api/v3/versions/12"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"availableInProjects": {
"href": "/api/v3/versions/12/projects"
}
},
"_type": "Version",
"id": 12,
"name": "v2.0",
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"startDate": null,
"endDate": null,
"status": "Closed"
},
{
"_links": {
"self": {
"href": "/api/v3/versions/10"
},
"definingProject": {
"href": "/api/v3/projects/13"
},
"availableInProjects": {
"href": "/api/v3/versions/13/projects"
}
},
"_type": "Version",
"id": 10,
"name": "v1.0",
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"startDate": null,
"endDate": null,
"status": "Open"
}
]
}
}
}
Create version
Creates a new version applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a version’s attributes and are accepted by the endpoint.
You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation.
No parameters
201
Created
VersionModel{
"type": "object",
"required": [
"name",
"status",
"sharing",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "integer",
"description": "Version id",
"readOnly": true,
"exclusiveMinimum": 0
},
"name": {
"type": "string",
"description": "Version name"
},
"description": {
"allOf": [
{
"$ref": "#/components/schemas/Formattable"
},
{
}
]
},
"startDate": {
"type": "string",
"format": "date"
},
"endDate": {
"type": "string",
"format": "date"
},
"status": {
"type": "string",
"description": "The current status of the version"
},
"sharing": {
"type": "string",
"description": "The current status of the version"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation",
"readOnly": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent change to the version",
"readOnly": true
},
"_links": {
"type": "object",
"required": [
"self",
"availableInProjects"
],
"properties": {
"update": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Form endpoint that aids in preparing and performing edits on the version\n\n# Conditions\n\n**Permission**: manage versions",
"readOnly": true
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly perform edits on the version\n\n# Conditions\n\n**Permission**: manage versions",
"readOnly": true
}
]
},
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This version\n\n**Resource**: Version",
"readOnly": true
}
]
},
"definingProject": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The project to which the version belongs\n\n**Resource**: Project",
"readOnly": true
}
]
},
"availableInProjects": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Projects where this version can be used\n\n**Resource**: Projects",
"readOnly": true
}
]
}
}
}
},
"example": {
"_links": {
"self": {
"href": "/api/v3/versions/11"
},
"update": {
"href": "/api/v3/versions/11/form",
"method": "POST"
},
"updateImmediately": {
"href": "/api/v3/versions/11",
"method": "PATCH"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
},
"customField4": {
"href": "/api/v3/custom_options/5",
"title": "Custom field option"
}
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "open",
"sharing": "system",
"customField14": "1234567890"
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: Manage versions
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
Available projects for versions
Gets a list of projects in which a version can be created in. The list contains all projects in which the user issuing the request has the manage versions permissions.
No parameters
200
OK
{
"_embedded": {
"elements": [
{
"_links": {
"categories": {
"href": "/api/v3/projects/6/categories"
},
"createWorkPackage": {
"href": "/api/v3/projects/6/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/6/work_packages",
"method": "post"
},
"editWorkPackage": {
"href": "/api/v3//work_packages/{id}/form",
"method": "post",
"templated": true
},
"self": {
"href": "/api/v3/projects/6",
"title": "A project"
},
"versions": {
"href": "/api/v3/projects/6/versions"
}
},
"_type": "Project",
"createdAt": "2015-07-06T13:28:14+00:00",
"description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
"id": 6,
"identifier": "a_project",
"name": "A project",
"type": "Customer Project",
"updatedAt": "2015-10-01T09:55:02+00:00"
},
{
"_links": {
"categories": {
"href": "/api/v3/projects/14/categories"
},
"createWorkPackage": {
"href": "/api/v3/projects/14/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/14/work_packages",
"method": "post"
},
"self": {
"href": "/api/v3/projects/14",
"title": "Another project"
},
"versions": {
"href": "/api/v3/projects/14/versions"
}
},
"_type": "Project",
"createdAt": "2016-02-29T12:50:20+00:00",
"description": "",
"id": 14,
"identifier": "another_project",
"name": "Another project",
"type": null,
"updatedAt": "2016-02-29T12:50:20+00:00"
}
]
},
"_links": {
"self": {
"href": "/api/v3/versions/available_projects"
}
},
"_type": "Collection",
"count": 2,
"total": 2
}
Available_projects_for_versionsModel{
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/versions/available_projects"
}
},
"_type": "Collection",
"total": 2,
"count": 2,
"_embedded": {
"elements": [
{
"_type": "Project",
"_links": {
"self": {
"href": "/api/v3/projects/6",
"title": "A project"
},
"editWorkPackage": {
"href": "/api/v3/work_packages/{id}/form",
"templated": true,
"method": "post"
},
"createWorkPackage": {
"href": "/api/v3/projects/6/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/6/work_packages",
"method": "post"
},
"categories": {
"href": "/api/v3/projects/6/categories"
},
"versions": {
"href": "/api/v3/projects/6/versions"
}
},
"id": 6,
"identifier": "a_project",
"name": "A project",
"description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
"createdAt": "2015-07-06T13:28:14+00:00",
"updatedAt": "2015-10-01T09:55:02+00:00",
"type": "Customer Project"
},
{
"_type": "Project",
"_links": {
"self": {
"href": "/api/v3/projects/14",
"title": "Another project"
},
"createWorkPackage": {
"href": "/api/v3/projects/14/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/14/work_packages",
"method": "post"
},
"categories": {
"href": "/api/v3/projects/14/categories"
},
"versions": {
"href": "/api/v3/projects/14/versions"
}
},
"id": 14,
"identifier": "another_project",
"name": "Another project",
"description": "",
"createdAt": "2016-02-29T12:50:20+00:00",
"updatedAt": "2016-02-29T12:50:20+00:00",
"type": null
}
]
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: manage versions
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Version create form
No parameters
200
OK
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: manage versions in any project
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View version schema
No parameters
200
OK
{
"_dependencies": [
],
"_links": {
"self": {
"href": "/api/v3/versions/schema"
}
},
"_type": "Schema",
"createdAt": {
"hasDefault": false,
"name": "Created on",
"required": true,
"type": "DateTime",
"writable": false
},
"customField14": {
"hasDefault": false,
"name": "text CF",
"required": false,
"type": "String",
"visibility": "default",
"writable": true
},
"customField40": {
"_links": {
},
"hasDefault": false,
"location": "_links",
"name": "List CF",
"required": false,
"type": "CustomOption",
"visibility": "default",
"writable": true
},
"definingProject": {
"_links": {
},
"hasDefault": false,
"name": "Project",
"required": true,
"type": "Project",
"writable": true
},
"description": {
"hasDefault": false,
"name": "Description",
"required": false,
"type": "Formattable",
"writable": true
},
"endDate": {
"hasDefault": false,
"name": "Finish date",
"required": false,
"type": "Date",
"writable": false
},
"id": {
"hasDefault": false,
"name": "ID",
"required": true,
"type": "Integer",
"writable": false
},
"name": {
"hasDefault": false,
"maxLength": 60,
"minLength": 1,
"name": "Name",
"required": true,
"type": "String",
"writable": true
},
"sharing": {
"_links": {
},
"hasDefault": false,
"name": "Sharing",
"required": true,
"type": "String",
"visibility": "default",
"writable": true
},
"startDate": {
"hasDefault": false,
"name": "Start date",
"required": false,
"type": "Date",
"writable": true
},
"status": {
"_links": {
},
"hasDefault": false,
"name": "Status",
"required": true,
"type": "String",
"visibility": "default",
"writable": true
},
"updatedAt": {
"hasDefault": false,
"name": "Updated on",
"required": true,
"type": "DateTime",
"writable": false
}
}
Version_schemaModel{
"type": "object",
"example": {
"_type": "Schema",
"_dependencies": [
],
"id": {
"type": "Integer",
"name": "ID",
"required": true,
"hasDefault": false,
"writable": false
},
"name": {
"type": "String",
"name": "Name",
"required": true,
"hasDefault": false,
"writable": true,
"minLength": 1,
"maxLength": 60
},
"description": {
"type": "Formattable",
"name": "Description",
"required": false,
"hasDefault": false,
"writable": true
},
"startDate": {
"type": "Date",
"name": "Start date",
"required": false,
"hasDefault": false,
"writable": true
},
"endDate": {
"type": "Date",
"name": "Finish date",
"required": false,
"hasDefault": false,
"writable": false
},
"status": {
"type": "String",
"name": "Status",
"required": true,
"hasDefault": false,
"writable": true,
"visibility": "default",
"_links": {
}
},
"sharing": {
"type": "String",
"name": "Sharing",
"required": true,
"hasDefault": false,
"writable": true,
"visibility": "default",
"_links": {
}
},
"createdAt": {
"type": "DateTime",
"name": "Created on",
"required": true,
"hasDefault": false,
"writable": false
},
"updatedAt": {
"type": "DateTime",
"name": "Updated on",
"required": true,
"hasDefault": false,
"writable": false
},
"definingProject": {
"type": "Project",
"name": "Project",
"required": true,
"hasDefault": false,
"writable": true,
"_links": {
}
},
"customField14": {
"type": "String",
"name": "text CF",
"required": false,
"hasDefault": false,
"writable": true,
"visibility": "default"
},
"customField40": {
"type": "CustomOption",
"name": "List CF",
"required": false,
"hasDefault": false,
"writable": true,
"location": "_links",
"visibility": "default",
"_links": {
}
},
"_links": {
"self": {
"href": "/api/v3/versions/schema"
}
}
}
}
403
Returned if the client does not have sufficient permissions to see the schema.
Required permission: view work packages or manage versions on any project
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View version
id
integer
required path
Version id
Example:1
200
OK
{
"_links": {
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
},
"customField4": {
"href": "/api/v3/custom_options/5",
"title": "Custom field option"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"self": {
"href": "/api/v3/versions/11"
},
"update": {
"href": "/api/v3/versions/11/form",
"method": "POST"
},
"updateImmediately": {
"href": "/api/v3/versions/11",
"method": "PATCH"
}
},
"_type": "Version",
"customField14": "1234567890",
"description": {
"format": "plain",
"html": "This version has a description",
"raw": "This version has a description"
},
"endDate": null,
"id": 11,
"name": "v3.0 Alpha",
"sharing": "system",
"startDate": "2014-11-20",
"status": "open"
}
VersionModel{
"type": "object",
"required": [
"name",
"status",
"sharing",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "integer",
"description": "Version id",
"readOnly": true,
"exclusiveMinimum": 0
},
"name": {
"type": "string",
"description": "Version name"
},
"description": {
"allOf": [
{
"$ref": "#/components/schemas/Formattable"
},
{
}
]
},
"startDate": {
"type": "string",
"format": "date"
},
"endDate": {
"type": "string",
"format": "date"
},
"status": {
"type": "string",
"description": "The current status of the version"
},
"sharing": {
"type": "string",
"description": "The current status of the version"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation",
"readOnly": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent change to the version",
"readOnly": true
},
"_links": {
"type": "object",
"required": [
"self",
"availableInProjects"
],
"properties": {
"update": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Form endpoint that aids in preparing and performing edits on the version\n\n# Conditions\n\n**Permission**: manage versions",
"readOnly": true
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly perform edits on the version\n\n# Conditions\n\n**Permission**: manage versions",
"readOnly": true
}
]
},
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This version\n\n**Resource**: Version",
"readOnly": true
}
]
},
"definingProject": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The project to which the version belongs\n\n**Resource**: Project",
"readOnly": true
}
]
},
"availableInProjects": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Projects where this version can be used\n\n**Resource**: Projects",
"readOnly": true
}
]
}
}
}
},
"example": {
"_links": {
"self": {
"href": "/api/v3/versions/11"
},
"update": {
"href": "/api/v3/versions/11/form",
"method": "POST"
},
"updateImmediately": {
"href": "/api/v3/versions/11",
"method": "PATCH"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
},
"customField4": {
"href": "/api/v3/custom_options/5",
"title": "Custom field option"
}
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "open",
"sharing": "system",
"customField14": "1234567890"
}
}
404
Returned if the version does not exist or the client does not have sufficient permissions to see it.
Required permission: view work packages or manage versions (any project where the version is available)
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Update version
Updates the given version by applying the attributes provided in the body. Please note that while there is a fixed set of attributes, custom fields can extend a version’s attributes and are accepted by the endpoint.
id
integer
required path
Version id
Example:1
200
OK
VersionModel{
"type": "object",
"required": [
"name",
"status",
"sharing",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "integer",
"description": "Version id",
"readOnly": true,
"exclusiveMinimum": 0
},
"name": {
"type": "string",
"description": "Version name"
},
"description": {
"allOf": [
{
"$ref": "#/components/schemas/Formattable"
},
{
}
]
},
"startDate": {
"type": "string",
"format": "date"
},
"endDate": {
"type": "string",
"format": "date"
},
"status": {
"type": "string",
"description": "The current status of the version"
},
"sharing": {
"type": "string",
"description": "The current status of the version"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation",
"readOnly": true
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Time of the most recent change to the version",
"readOnly": true
},
"_links": {
"type": "object",
"required": [
"self",
"availableInProjects"
],
"properties": {
"update": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Form endpoint that aids in preparing and performing edits on the version\n\n# Conditions\n\n**Permission**: manage versions",
"readOnly": true
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly perform edits on the version\n\n# Conditions\n\n**Permission**: manage versions",
"readOnly": true
}
]
},
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This version\n\n**Resource**: Version",
"readOnly": true
}
]
},
"definingProject": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The project to which the version belongs\n\n**Resource**: Project",
"readOnly": true
}
]
},
"availableInProjects": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Projects where this version can be used\n\n**Resource**: Projects",
"readOnly": true
}
]
}
}
}
},
"example": {
"_links": {
"self": {
"href": "/api/v3/versions/11"
},
"update": {
"href": "/api/v3/versions/11/form",
"method": "POST"
},
"updateImmediately": {
"href": "/api/v3/versions/11",
"method": "PATCH"
},
"definingProject": {
"href": "/api/v3/projects/11"
},
"availableInProjects": {
"href": "/api/v3/versions/11/projects"
},
"customField4": {
"href": "/api/v3/custom_options/5",
"title": "Custom field option"
}
},
"_type": "Version",
"id": 11,
"name": "v3.0 Alpha",
"description": {
"format": "plain",
"raw": "This version has a description",
"html": "This version has a description"
},
"startDate": "2014-11-20",
"endDate": null,
"status": "open",
"sharing": "system",
"customField14": "1234567890"
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: Manage versions in the version’s project.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the version does not exist or the client does not have sufficient permissions to see it.
Required permission: view work packages or manage versions (any project where the version is available)
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
Delete version
Deletes the version. Work packages associated to the version will no longer be assigned to it.
id
integer
required path
Version id
Example:1
204
Returned if the version was successfully deleted
403
Returned if the client does not have sufficient permissions.
Required permission: manage versions
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the version does not exist or the client does not have sufficient permissions to see it.
Required permission: view work packages or manage versions (any project where the version is available)
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Version update form
id
integer
required path
Project id
Example:1
200
OK
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: manage versions in the version’s project
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
