Table of contents

On this page

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

get /api/v3/projects/{id}/versions

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

Content-Type: application/hal+json

Example
Schema

{
  "_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

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects/11/versions"
      }
    },
    "total": 3,
    "count": 3,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_links": {
            "self": {
              "href": "/api/v3/versions/11"
            },
            "definingProject": {
              "href": "/api/v3/projects/11"
            },
            "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/11"
            },
            "availableInProjects": {
              "href": "/api/v3/versions/10/projects"
            }
          },
          "_type": "Version",
          "id": 10,
          "name": "v1.0",
          "description": {
            "format": "plain",
            "raw": "",
            "html": ""
          },
          "startDate": null,
          "endDate": null,
          "status": "Open"
        }
      ]
    }
  }
}

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.

Content-Type: application/hal+json

Example
Schema

{
  "_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

get /api/v3/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

Content-Type: application/hal+json

Example
Schema

{
  "_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

post /api/v3/versions

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

Content-Type: application/hal+json

Schema

VersionModel

{
  "type": "object",
  "required": [
    "name",
    "status",
    "sharing",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Version id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "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

403

Returned if the client does not have sufficient permissions.

Required permission: Manage versions

Content-Type: application/hal+json

Example
Schema

{
  "_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

422

Returned if:

a constraint for a property was violated (PropertyConstraintViolation)

Available projects for versions

get /api/v3/versions/available_projects

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

Content-Type: application/hal+json

Example
Schema

{
  "_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

Content-Type: application/hal+json

Example
Schema

{
  "_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

post /api/v3/versions/form

No parameters

200

OK

400

403

Returned if the client does not have sufficient permissions.

Required permission: manage versions in any project

Content-Type: application/hal+json

Example
Schema

{
  "_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

View version schema

get /api/v3/versions/schema

No parameters

200

OK

Content-Type: application/hal+json

Example
Schema

{
  "_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

Content-Type: application/hal+json

Example
Schema

{
  "_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

get /api/v3/versions/{id}

id
integer

required path

Version id

Example:
1

200

OK

Content-Type: application/hal+json

Example
Schema

{
  "_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,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "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.

Content-Type: application/hal+json

Example
Schema

{
  "_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

patch /api/v3/versions/{id}

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

Content-Type: application/hal+json

Schema

VersionModel

{
  "type": "object",
  "required": [
    "name",
    "status",
    "sharing",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Version id",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "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

403

Returned if the client does not have sufficient permissions.

Required permission: Manage versions in the version’s project.

Content-Type: application/hal+json

Example
Schema

{
  "_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.

Content-Type: application/hal+json

Example
Schema

{
  "_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

422

Returned if:

a constraint for a property was violated (PropertyConstraintViolation)

Delete version

delete /api/v3/versions/{id}

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

Content-Type: application/hal+json

Example
Schema

{
  "_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.

Content-Type: application/hal+json

Example
Schema

{
  "_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

Version update form

post /api/v3/versions/{id}/form

id
integer

required path

Project id

Example:
1

200

OK

400

403

Returned if the client does not have sufficient permissions.

Required permission: manage versions in the version’s project

Content-Type: application/hal+json

Example
Schema

{
  "_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

Help and feedback

If you did not find what you were looking for

If you need help from the community or want to support others

Post on OpenProject forum

If you are eligible for professional support and have more questions

Request support

If you find an easily fixable error or need for improvement in the documentation

If you would like to suggest bigger updates or improvements to this documentation

Create an issue

If you want to contribute to translate this documentation to another language

Translate on crowdin

If there’s something you don’t like or understand about this feature

Create an issue

If you want to propose a new feature that OpenProject does not offer yet

Submit feature proposal

To further help OpenProject to shape and test new features

Join beta testing

To view OpenProject Enterprise add-ons and pricing

View pricing page

If you want to try all Enterprise add-ons in the OpenProject Enterprise cloud 14 days for free

Free trial OpenProject Enterprise cloud

If you want to try all Enterprise add-ons in your on premise Community installation 14 days for free

Free trial OpenProject Enterprise on premises

JavaScript deactivated. Many features of this site do not work without JavaScript. More information

Most popular topics