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

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

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

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

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

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

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

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

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

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

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

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."
    }
  }
}