API: Projects

Projects are containers structuring the information (e.g. work packages, wikis) into smaller groups. They can be used in a classic project management approach but also when structuring work by departments.

As containers, they also control behaviour of the elements within them. One of the most important aspects of this is that projects limit permissions by having members with a certain permission set (roles) assigned to them.

Link Description Condition
update Form endpoint that aids in updating this project Permission : edit project
updateImmediately Directly update this project Permission : edit project
delete Delete this project Permission : admin
createWorkPackage Form endpoint that aids in preparing and creating a work package Permission : add work packages
createWorkPackageImmediately Directly creates a work package in the project Permission : add work packages

Link Description Type Constraints Supported operations Condition
self This project Project not null READ
ancestors Array of all ancestors of the project, down from the root node (first element) to the parent (last element). Collection not null READ Permission view project on the ancestor project. Non visible projects will be omitted
categories Categories available in this project Collection not null READ
types Types available in this project Collection not null READ Permission : view work packages or manage types
versions Versions available in this project Collection not null READ Permission : view work packages or manage versions
memberships Memberships in the project Collection not null READ Permission : view members
workPackages Work Packages of this project Collection not null READ
parent Parent project of the project Project READ/WRITE Permission edit project
status Denotes the status of the project, so whether the project is on track, at risk or is having trouble. ProjectStatus READ/WRITE Permission edit project

general introduction into links’ properties for more information.

Property Description Type Constraints Supported operations
id Projects’ id Integer x > 0 READ/WRITE
identifier String READ/WRITE
name String READ/WRITE
active Indicates whether the project is currently active or already archived Boolean READ/WRITE
statusExplanation A text detailing and explaining why the project has the reported status Formattable READ/WRITE
public Indicates whether the project is accessible for everybody Boolean READ/WRITE
description Formattable READ/WRITE
createdAt Time of creation DateTime READ
updatedAt Time of the most recent change to the project DateTime READ

List projects

Returns a collection of projects. The collection can be filtered via query parameters similar to how work packages are filtered. In addition to the provided filter, the result set is always limited to only contain projects the client is allowed to see.

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • active: based on the active property of the project
  • ancestor: filters projects by their ancestor. A project is not considered to be it’s own ancestor.
  • available_project_attributes: filters projects based on the activated project project attributes.
  • created_at: based on the time the project was created
  • latest_activity_at: based on the time the last activity was registered on a project.
  • name_and_identifier: based on both the name and the identifier.
  • parent_id: filters projects by their parent.
  • principal: based on members of the project.
  • storage_id: filters projects by linked storages
  • storage_url: filters projects by linked storages identified by the host url
  • type_id: based on the types active in a project.
  • user_action: based on the actions the current user has in the project.
  • id: based on projects’ id.
  • visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the projects visible to a user.

There might also be additional filters based on the custom fields that have been configured.

Example:
[{ "ancestor": { "operator": "=", "values": ["1"] }" }]

sortBy
string

optional query

JSON specifying sort criteria. Currently supported orders are:

  • id
  • name
  • typeahead (sorting by hierarchy and name)
  • created_at
  • public
  • latest_activity_at
  • required_disk_space

There might also be additional orders based on the custom fields that have been configured.

Example:
[["id", "asc"]]

select
string

optional query

Comma separated list of properties to include.

Example:
total,elements/identifier,elements/name

400

Create project

Creates a new project, applying the attributes provided in the body.

You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation.

No parameters 
{
  "_type": {
    "type": "string",
    "enum": [
      "Project"
  "id": {
    "type": "integer",
    "description": "Projects' id",
    "minimum": 1
  "identifier": {
    "type": "string"
  "name": {
    "type": "string"
  "active": {
    "type": "boolean",
    "description": "Indicates whether the project is currently active or already archived"
  "statusExplanation": {
    "allOf": [
        "$ref": "#/components/schemas/Formattable"
        "description": "A text detailing and explaining why the project has the reported status"
  "public": {
    "type": "boolean",
    "description": "Indicates whether the project is accessible for everybody"
  "description": {
    "$ref": "#/components/schemas/Formattable"
  "createdAt": {
    "type": "string",
    "format": "date-time",
    "description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled."
  "updatedAt": {
    "type": "string",
    "format": "date-time",
    "description": "Time of the most recent change to the project"
  "_links": {
    "type": "object",
    "required": [
      "self",
      "categories",
      "types",
      "versions",
      "memberships",
      "workPackages"
    "properties": {
      "update": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Form endpoint that aids in updating this project\n\n# Conditions\n\n**Permission**: edit project"
      "updateImmediately": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit project"
      "delete": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
      "createWorkPackage": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Form endpoint that aids in preparing and creating a work package\n\n# Conditions\n\n**Permission**: add work packages"
      "createWorkPackageImmediately": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Directly creates a work package in the project\n\n# Conditions\n\n**Permission**: add work packages"
      "self": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "This project\n\n**Resource**: Project"
      "categories": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Categories available in this project\n\n**Resource**: Collection"
      "types": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Types available in this project\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view work packages or manage types"
      "versions": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Versions available in this project\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view work packages or manage versions"
      "memberships": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Memberships in the  project\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view members"
      "workPackages": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Work Packages of this project\n\n**Resource**: Collection"
      "parent": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Parent project of the project\n\n**Resource**: Project\n\n# Conditions\n\n**Permission** edit project"
      "status": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "Denotes the status of the project, so whether the project is on track, at risk or is having trouble.\n\n**Resource**: ProjectStatus\n\n# Conditions\n\n**Permission** edit project"
      "storages": {
        "type": "array",
        "items": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "The link to a storage that is active for this project.\n\n**Resource**: Storage\n\n# Conditions\n\n**Permission**: view_file_links"
      "projectStorages": {
        "allOf": [
            "$ref": "#/components/schemas/Link"
            "description": "The project storage collection of this project.\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view_file_links"
      "ancestors": {
        "type": "array",
        "items": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "The link to an ancestor project.\n\n**Resource**: Project"

201

Created 

{
  "_type": "Project",
  "_links": {
    "self": {
      "href": "/api/v3/projects/1",
      "title": "Lorem"
    "createWorkPackage": {
      "href": "/api/v3/projects/1/work_packages/form",
      "method": "post"
    "createWorkPackageImmediate": {
      "href": "/api/v3/projects/1/work_packages",
      "method": "post"
    "categories": {
      "href": "/api/v3/projects/1/categories"
    "types": {
      "href": "/api/v3/projects/1/types"
    "versions": {
      "href": "/api/v3/projects/1/versions"
    "workPackages": {
      "href": "/api/v3/projects/1/work_packages"
    "memberships": {
      "href": "/api/v3/memberships?filters=[{\"project\":{\"operator\":\"=\",\"values\":[\"1\"]}}]"
    "customField456": {
      "href": "/api/v3/users/315",
      "title": "A user"
    "parent": {
      "href": "/api/v3/projects/123",
      "title": "Parent project"
    "ancestors": [
        "href": "/api/v3/projects/2",
        "title": "Root project"
        "href": "/api/v3/projects/12",
        "title": "Grandparent project"
        "href": "/api/v3/projects/123",
        "title": "Parent project"
    "status": {
      "href": "/api/v3/project_statuses/on_track",
      "title": "On track"
  "id": 1,
  "identifier": "project_example",
  "name": "Project example",
  "active": true,
  "public": false,
  "statusExplanation": {
    "format": "markdown",
    "raw": "Everything **fine**",
    "html": "<p>Everything <strong>fine</strong></p>"
  "description": {
    "format": "markdown",
    "raw": "Lorem **ipsum** dolor sit amet",
    "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
  "createdAt": "2014-05-21T08:51:20.396Z",
  "updatedAt": "2014-05-21T08:51:20.396Z",
  "customField123": 123
ProjectModel 
{
  "type": "object",
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Project"
    "id": {
      "type": "integer",
      "description": "Projects' id",
      "minimum": 1
    "identifier": {
      "type": "string"
    "name": {
      "type": "string"
    "active": {
      "type": "boolean",
      "description": "Indicates whether the project is currently active or already archived"
    "statusExplanation": {
      "allOf": [
          "$ref": "#/components/schemas/Formattable"
          "description": "A text detailing and explaining why the project has the reported status"
    "public": {
      "type": "boolean",
      "description": "Indicates whether the project is accessible for everybody"
    "description": {
      "$ref": "#/components/schemas/Formattable"
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled."
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the project"
    "_links": {
      "type": "object",
      "required": [
        "self",
        "categories",
        "types",
        "versions",
        "memberships",
        "workPackages"
      "properties": {
        "update": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Form endpoint that aids in updating this project\n\n# Conditions\n\n**Permission**: edit project"
        "updateImmediately": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit project"
        "delete": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
        "createWorkPackage": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Form endpoint that aids in preparing and creating a work package\n\n# Conditions\n\n**Permission**: add work packages"
        "createWorkPackageImmediately": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Directly creates a work package in the project\n\n# Conditions\n\n**Permission**: add work packages"
        "self": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "This project\n\n**Resource**: Project"
        "categories": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Categories available in this project\n\n**Resource**: Collection"
        "types": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Types available in this project\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view work packages or manage types"
        "versions": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Versions available in this project\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view work packages or manage versions"
        "memberships": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Memberships in the  project\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view members"
        "workPackages": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Work Packages of this project\n\n**Resource**: Collection"
        "parent": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Parent project of the project\n\n**Resource**: Project\n\n# Conditions\n\n**Permission** edit project"
        "status": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "Denotes the status of the project, so whether the project is on track, at risk or is having trouble.\n\n**Resource**: ProjectStatus\n\n# Conditions\n\n**Permission** edit project"
        "storages": {
          "type": "array",
          "items": {
            "allOf": [
                "$ref": "#/components/schemas/Link"
                "description": "The link to a storage that is active for this project.\n\n**Resource**: Storage\n\n# Conditions\n\n**Permission**: view_file_links"
        "projectStorages": {
          "allOf": [
              "$ref": "#/components/schemas/Link"
              "description": "The project storage collection of this project.\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission**: view_file_links"
        "ancestors": {
          "type": "array",
          "items": {
            "allOf": [
                "$ref": "#/components/schemas/Link"
                "description": "The link to an ancestor project.\n\n**Resource**: Project"

400

Occurs when the client did not send a valid JSON object in the request body.

403

Returned if the client does not have sufficient permissions.

Required permission: add project which is a global permission

406

415

Occurs when the client sends an unsupported Content-Type header.

422

Returned if:

  • a constraint for a property was violated ( PropertyConstraintViolation )

List available parent project candidates

Lists projects which can become parent to another project. Only sound candidates are returned. For instance a project cannot become parent of itself or it’s children.

To specify the project for which a parent is queried for, the of parameter can be provided. If no of parameter is provided, a new project is assumed. Then, the check for the hierarchy is omitted as a new project cannot be part of a hierarchy yet.

Candidates can be filtered. Most commonly one will want to filter by name or identifier. You can do this through the filters parameter which works just like the work package index.

For instance to find all parent candidates with “rollout” in their name: 

?filters=[{"name_and_identifier":{"operator":"~","values":["rollout"]}}]

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"
          "self": {
            "href": "/api/v3/projects/6",
            "title": "A project"
          "status": {
            "href": "/api/v3/project_statuses/on_track",
            "title": "On track"
          "versions": {
            "href": "/api/v3/projects/6/versions"
        "_type": "Project",
        "active": true,
        "createdAt": "2015-07-06T13:28:14+00:00",
        "description": {
          "format": "markdown",
          "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>",
          "raw": "Lorem **ipsum** dolor sit amet"
        "id": 6,
        "identifier": "a_project",
        "name": "A project",
        "public": false,
        "statusExplanation": {
          "format": "markdown",
          "html": "<p>Everything <strong>fine</strong></p>",
          "raw": "Everything **fine**"
        "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"
          "status": {
            "href": "/api/v3/project_statuses/on_track",
            "title": "On track"
          "versions": {
            "href": "/api/v3/projects/14/versions"
        "_type": "Project",
        "active": true,
        "createdAt": "2016-02-29T12:50:20+00:00",
        "description": {
          "format": "markdown",
          "html": "",
          "raw": ""
        "id": 14,
        "identifier": "another_project",
        "name": "Another project",
        "public": true,
        "statusExplanation": {
          "format": "markdown",
          "html": "<p>Everything super <strong>fine</strong></p>",
          "raw": "Everything super **fine**"
        "type": null,
        "updatedAt": "2016-02-29T12:50:20+00:00"
  "_links": {
    "self": {
      "href": "/api/v3/projects/available_parent_projects?of=123"
  "_type": "Collection",
  "count": 2,
  "total": 2

403

Returned if the client does not have sufficient permissions.

Required permission: edit project in a project or the global add project permission

Project create form

No parameters 
{
  "type": "object"

200

OK 

{
  "_embedded": {
    "payload": {
      "_links": {
        "customField26": {
          "href": null,
          "title": null
        "customField31": {
          "href": null,
          "title": null
        "parent": {
          "href": null
        "status": {
          "href": null
      "active": true,
      "customField30": null,
      "customField34": null,
      "customField35": "Text custom field value",
      "customField41": {
        "format": "markdown",
        "html": "",
        "raw": ""
      "customField42": null,
      "description": {
        "format": "markdown",
        "html": "",
        "raw": null
      "identifier": "new_project_identifier",
      "name": "New project name",
      "public": false,
      "statusExplanation": {
        "format": "markdown",
        "html": "<p></p>",
        "raw": null
    "schema": {
      "_dependencies": [
      "_links": {
      "_type": "Schema",
      "active": {
        "hasDefault": true,
        "name": "Active",
        "required": true,
        "type": "Boolean",
        "writable": true
      "createdAt": {
        "hasDefault": false,
        "name": "Created on",
        "required": true,
        "type": "DateTime",
        "writable": false
      "customField26": {
        "_links": {
          "allowedValues": {
            "href": "/api/v3/principals?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%220%22%2C%223%22%5D%7D%7D%2C%7B%22type%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22User%22%5D%7D%7D%2C%7B%22member%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22%22%5D%7D%7D%5D&pageSize=0"
        "hasDefault": false,
        "location": "_links",
        "name": "Project user",
        "required": false,
        "type": "User",
        "visibility": "default",
        "writable": true
      "customField30": {
        "hasDefault": false,
        "name": "some project cf",
        "required": false,
        "type": "Integer",
        "visibility": "default",
        "writable": true
      "customField31": {
        "_embedded": {
          "allowedValues": [
              "_links": {
                "self": {
                  "href": "/api/v3/custom_options/513",
                  "title": "abc"
              "_type": "CustomOption",
              "id": 513,
              "value": "abc"
              "_links": {
                "self": {
                  "href": "/api/v3/custom_options/514",
                  "title": "def"
              "_type": "CustomOption",
              "id": 514,
              "value": "def"
              "_links": {
                "self": {
                  "href": "/api/v3/custom_options/515",
                  "title": "ghi"
              "_type": "CustomOption",
              "id": 515,
              "value": "ghi"
        "_links": {
          "allowedValues": [
              "href": "/api/v3/custom_options/513",
              "title": "abc"
              "href": "/api/v3/custom_options/514",
              "title": "def"
              "href": "/api/v3/custom_options/515",
              "title": "ghi"
        "hasDefault": false,
        "location": "_links",
        "name": "list project cf",
        "required": false,
        "type": "CustomOption",
        "visibility": "default",
        "writable": true
      "customField34": {
        "hasDefault": false,
        "name": "Bool Project CF",
        "required": false,
        "type": "Boolean",
        "visibility": "default",
        "writable": true
      "customField35": {
        "hasDefault": false,
        "name": "text project cf",
        "required": true,
        "type": "String",
        "visibility": "default",
        "writable": true
      "customField41": {
        "hasDefault": false,
        "name": "Long text project cf",
        "required": false,
        "type": "Formattable",
        "visibility": "default",
        "writable": true
      "customField42": {
        "hasDefault": false,
        "name": "Date project cf",
        "required": false,
        "type": "Date",
        "visibility": "default",
        "writable": true
      "description": {
        "hasDefault": false,
        "name": "Description",
        "required": false,
        "type": "Formattable",
        "writable": true
      "id": {
        "hasDefault": false,
        "name": "ID",
        "required": true,
        "type": "Integer",
        "writable": false
      "identifier": {
        "hasDefault": false,
        "maxLength": 100,
        "minLength": 1,
        "name": "Identifier",
        "required": true,
        "type": "String",
        "writable": true
      "name": {
        "hasDefault": false,
        "maxLength": 255,
        "minLength": 1,
        "name": "Name",
        "required": true,
        "type": "String",
        "writable": true
      "parent": {
        "_links": {
          "allowedValues": {
            "href": "/api/v3/projects/available_parent_projects"
        "hasDefault": false,
        "location": "_links",
        "name": "Subproject of",
        "required": false,
        "type": "Project",
        "visibility": "default",
        "writable": true
      "public": {
        "hasDefault": false,
        "name": "Public",
        "required": true,
        "type": "Boolean",
        "writable": true
      "status": {
        "_links": {
          "allowedValues": [
              "href": "/api/v3/project_statuses/on_track",
              "title": "On track"
              "href": "/api/v3/project_statuses/at_risk",
              "title": "At risk"
              "href": "/api/v3/project_statuses/off_track",
              "title": "Off track"
        "hasDefault": true,
        "name": "Status",
        "required": false,
        "type": "ProjectStatus",
        "writable": true
      "statusExplanation": {
        "hasDefault": false,
        "name": "Status explanation",
        "required": false,
        "type": "Formattable",
        "writable": true
      "updatedAt": {
        "hasDefault": false,
        "name": "Updated on",
        "required": true,
        "type": "DateTime",
        "writable": false
    "validationErrors": {
      "identifier": {
        "_embedded": {
          "details": {
            "attribute": "identifier"
        "_type": "Error",
        "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
        "message": "Identifier has already been taken."
  "_links": {
    "self": {
      "href": "/api/v3/projects/form",
      "method": "post"
    "validate": {
      "href": "/api/v3/projects/form",
      "method": "post"
  "_type": "Form"
  "type": "object"

400

Occurs when the client did not send a valid JSON object in the request body.

403

Returned if the client does not have sufficient permissions.

Required permission: add project which is a global permission

406

415

Occurs when the client sends an unsupported Content-Type header.