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.

Actions

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

Linked Properties

Link Description Type Constraints Supported operations Condition
self This project Project not null READ  
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

Depending on custom fields defined for projects, additional links might exist.

Note, that the parent link may contain the “undisclosed uri” urn:openproject-org:api:v3:undisclosed in case a parent project is defined but the client lacks permission to see it. See the general introduction into links’ properties for more information.

Local Properties

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

Depending on custom fields defined for projects, additional properties might exist.

Methods

View project status

id
string

required path

Project status id

Example:
on_track

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/project_statuses/on_track"
    }
  },
  "_type": "ProjectStatus",
  "id": "on_track",
  "name": "On track"
}

View_project_statusModel

{
  "type": "object",
  "example": {
    "_type": "ProjectStatus",
    "id": "on_track",
    "name": "On track",
    "_links": {
      "self": {
        "href": "/api/v3/project_statuses/on_track"
      }
    }
  }
}

404

Returned if the project status does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}

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.

  • 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.

  • 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

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

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"
          },
          "projects": {
            "href": "/api/v3/projects/123"
          },
          "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"
          },
          "projects": {
            "href": null
          },
          "self": {
            "href": "/api/v3/projects/14",
            "title": "Another project"
          },
          "status": {
            "href": "/api/v3/project_statuses/off_track",
            "title": "Off track"
          },
          "versions": {
            "href": "/api/v3/projects/14/versions"
          }
        },
        "_type": "Project",
        "active": false,
        "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>Uh <strong>oh</strong></p>",
          "raw": "Uh **oh**"
        },
        "type": null,
        "updatedAt": "2016-02-29T12:50:20+00:00"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}

List_projectsModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects"
      }
    },
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_embedded": {
      "elements": [
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/6",
              "title": "A project"
            },
            "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"
            },
            "projects": {
              "href": "/api/v3/projects/123"
            },
            "status": {
              "href": "/api/v3/project_statuses/on_track",
              "title": "On track"
            }
          },
          "id": 6,
          "identifier": "a_project",
          "name": "A project",
          "active": true,
          "statusExplanation": {
            "format": "markdown",
            "raw": "Everything **fine**",
            "html": "<p>Everything <strong>fine</strong></p>"
          },
          "public": false,
          "description": {
            "format": "markdown",
            "raw": "Lorem **ipsum** dolor sit amet",
            "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
          },
          "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"
            },
            "projects": {
              "href": null
            },
            "status": {
              "href": "/api/v3/project_statuses/off_track",
              "title": "Off track"
            }
          },
          "id": 14,
          "identifier": "another_project",
          "name": "Another project",
          "active": false,
          "statusExplanation": {
            "format": "markdown",
            "raw": "Uh **oh**",
            "html": "<p>Uh <strong>oh</strong></p>"
          },
          "public": true,
          "description": {
            "format": "markdown",
            "raw": "",
            "html": ""
          },
          "createdAt": "2016-02-29T12:50:20+00:00",
          "updatedAt": "2016-02-29T12:50:20+00:00",
          "type": null
        }
      ]
    }
  }
}

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

201

Created

View_projectModel

{
  "type": "object",
  "example": {
    "_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",
        "method": "A user"
      },
      "projects": {
        "href": "/api/v3/projects/123"
      },
      "status": {
        "href": "/api/v3/project_statuses/on_track",
        "title": "On track"
      }
    },
    "id": 1,
    "identifier": "project_identifier",
    "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:20Z",
    "updatedAt": "2014-05-21T08:51:20Z",
    "customField123": 123
  }
}

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

403

Returned if the client does not have sufficient permissions.

Required permission: add project which is a global permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name can't be blank."
}

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

filters
string

optional query

JSON specifying filter conditions.

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

of
string

optional query

The id or identifier of the project the parent candidate is determined for

Example:
123

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint and allows all the filters and sortBy supported by the project list end point.

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

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
}

List_available_parent_project_candidatesModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects/available_parent_projects?of=123"
      }
    },
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_embedded": {
      "elements": [
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/6",
              "title": "A project"
            },
            "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"
            },
            "status": {
              "href": "/api/v3/project_statuses/on_track",
              "title": "On track"
            }
          },
          "id": 6,
          "identifier": "a_project",
          "name": "A project",
          "active": true,
          "statusExplanation": {
            "format": "markdown",
            "raw": "Everything **fine**",
            "html": "<p>Everything <strong>fine</strong></p>"
          },
          "public": false,
          "description": {
            "format": "markdown",
            "raw": "Lorem **ipsum** dolor sit amet",
            "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
          },
          "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"
            },
            "status": {
              "href": "/api/v3/project_statuses/on_track",
              "title": "On track"
            }
          },
          "id": 14,
          "identifier": "another_project",
          "name": "Another project",
          "active": true,
          "statusExplanation": {
            "format": "markdown",
            "raw": "Everything super **fine**",
            "html": "<p>Everything super <strong>fine</strong></p>"
          },
          "public": true,
          "description": {
            "format": "markdown",
            "raw": "",
            "html": ""
          },
          "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: edit project in a project or the global add project permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

Project create form

No parameters

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

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

403

Returned if the client does not have sufficient permissions.

Required permission: add project which is a global permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

View project schema

No parameters

200

OK

{
  "_dependencies": [

  ],
  "_links": {
    "self": {
      "href": "/api/v3/projects/schema"
    }
  },
  "_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
  },
  "customField30": {
    "hasDefault": false,
    "name": "Integer project custom field",
    "required": false,
    "type": "Integer",
    "visibility": "default",
    "writable": true
  },
  "customField31": {
    "_links": {
    },
    "hasDefault": false,
    "location": "_links",
    "name": "List project custom field",
    "required": false,
    "type": "CustomOption",
    "visibility": "default",
    "writable": true
  },
  "customField32": {
    "_links": {
    },
    "hasDefault": false,
    "location": "_links",
    "name": "Version project custom field",
    "required": false,
    "type": "Version",
    "visibility": "default",
    "writable": true
  },
  "customField34": {
    "hasDefault": false,
    "name": "Boolean project custom field",
    "required": false,
    "type": "Boolean",
    "visibility": "default",
    "writable": true
  },
  "customField35": {
    "hasDefault": false,
    "name": "Text project custom field",
    "required": true,
    "type": "String",
    "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": {
    },
    "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
  }
}

Projects_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": 255
    },
    "identifier": {
      "type": "String",
      "name": "Identifier",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "type": "Formattable",
      "name": "Description",
      "required": false,
      "hasDefault": false,
      "writable": true
    },
    "public": {
      "type": "Boolean",
      "name": "Public",
      "required": true,
      "hasDefault": false,
      "writable": true
    },
    "active": {
      "type": "Boolean",
      "name": "Active",
      "required": true,
      "hasDefault": true,
      "writable": true
    },
    "status": {
      "type": "ProjectStatus",
      "name": "Status",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "_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"
          }
        ]
      }
    },
    "statusExplanation": {
      "type": "Formattable",
      "name": "Status explanation",
      "required": false,
      "hasDefault": false,
      "writable": true
    },
    "parent": {
      "type": "Project",
      "name": "Subproject of",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links",
      "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
    },
    "customField30": {
      "type": "Integer",
      "name": "Integer project custom field",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "visibility": "default"
    },
    "customField31": {
      "type": "CustomOption",
      "name": "List project custom field",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links",
      "visibility": "default",
      "_links": {
      }
    },
    "customField32": {
      "type": "Version",
      "name": "Version project custom field",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links",
      "visibility": "default",
      "_links": {
      }
    },
    "customField34": {
      "type": "Boolean",
      "name": "Boolean project custom field",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "visibility": "default"
    },
    "customField35": {
      "type": "String",
      "name": "Text project custom field",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "visibility": "default"
    },
    "_links": {
      "self": {
        "href": "/api/v3/projects/schema"
      }
    }
  }
}

View project

id
integer

required path

Project id

Example:
1

200

OK

{
  "_links": {
    "categories": {
      "href": "/api/v3/projects/1/categories"
    },
    "createWorkPackage": {
      "href": "/api/v3/projects/1/work_packages/form",
      "method": "post"
    },
    "createWorkPackageImmediate": {
      "href": "/api/v3/projects/1/work_packages",
      "method": "post"
    },
    "customField456": {
      "href": "/api/v3/users/315",
      "method": "A user"
    },
    "memberships": {
      "href": "/api/v3/memberships?filters=[{\"project\":{\"operator\":\"=\",\"values\":[\"1\"]}}]"
    },
    "projects": {
      "href": "/api/v3/projects/123"
    },
    "self": {
      "href": "/api/v3/projects/1",
      "title": "Lorem"
    },
    "status": {
      "href": "/api/v3/project_statuses/on_track",
      "title": "On track"
    },
    "types": {
      "href": "/api/v3/projects/1/types"
    },
    "versions": {
      "href": "/api/v3/projects/1/versions"
    },
    "workPackages": {
      "href": "/api/v3/projects/1/work_packages"
    }
  },
  "_type": "Project",
  "active": true,
  "createdAt": "2014-05-21T08:51:20Z",
  "customField123": 123,
  "description": {
    "format": "markdown",
    "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>",
    "raw": "Lorem **ipsum** dolor sit amet"
  },
  "id": 1,
  "identifier": "project_identifier",
  "name": "Project example",
  "public": false,
  "statusExplanation": {
    "format": "markdown",
    "html": "<p>Everything <strong>fine</strong></p>",
    "raw": "Everything **fine**"
  },
  "updatedAt": "2014-05-21T08:51:20Z"
}

View_projectModel

{
  "type": "object",
  "example": {
    "_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",
        "method": "A user"
      },
      "projects": {
        "href": "/api/v3/projects/123"
      },
      "status": {
        "href": "/api/v3/project_statuses/on_track",
        "title": "On track"
      }
    },
    "id": 1,
    "identifier": "project_identifier",
    "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:20Z",
    "updatedAt": "2014-05-21T08:51:20Z",
    "customField123": 123
  }
}

404

Returned if the project does not exist or the client does not have sufficient permissions to see it.

Required permission: view 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 requested resource could not be found."
}

Update project

Updates the given project by applying the attributes provided in the body.

id
integer

required path

Project id

Example:
1

200

OK

View_projectModel

{
  "type": "object",
  "example": {
    "_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",
        "method": "A user"
      },
      "projects": {
        "href": "/api/v3/projects/123"
      },
      "status": {
        "href": "/api/v3/project_statuses/on_track",
        "title": "On track"
      }
    },
    "id": 1,
    "identifier": "project_identifier",
    "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:20Z",
    "updatedAt": "2014-05-21T08:51:20Z",
    "customField123": 123
  }
}

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

403

Returned if the client does not have sufficient permissions.

Required permission: edit project for the project to be altered

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the project does not exist or the client does not have sufficient permissions to see it.

Required permission: view project

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

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name can't be blank."
}

Delete project

Deletes the project permanently. As this is a lengthy process, the actual deletion is carried out asynchronously. So the project might exist well after the request has returned successfully. To prevent unwanted changes to the project scheduled for deletion, it is archived at once.

id
integer

required path

Project id

Example:
1

204

Returned if the project was successfully deleted. There is currently no end point to query for the actual deletion status. Such an end point might be added in the future.

403

Returned if the client does not have sufficient permissions.

Required permission: admin

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

404

Returned if the project does not exist or the client does not have sufficient permissions to see it.

Required permission: view project

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

422

Returned if the project cannot be deleted. This can happen when there are still references to the project in other projects that need to be severed at first.

{
  "_embedded": {
    "details": {
      "attribute": "base"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Work packages in non descendant projects reference versions of the project or its descendants."
}

Create project copy

id
integer

required path

Project id

Example:
1

302

Returned if the request is successful. It will redirect to the job statuses API with the backend job that got created. You can query that endpoint to check the status of the copy, and eventually get the created project.

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

403

Returned if the client does not have sufficient permissions.

Required permission: copy projects in the source project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name can't be blank."
}

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

403

Returned if the client does not have sufficient permissions.

Required permission: copy projects in the source project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

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

403

Returned if the client does not have sufficient permissions.

Required permission: edit projects in the project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}

List projects with version

This endpoint lists the projects where the given version is available.

The projects returned depend on the sharing settings of the given version, but are also limited to the projects that the current user is allowed to see.

id
integer

required path

Version id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "categories": {
            "href": "/api/v3/projects/1/categories"
          },
          "self": {
            "href": "/api/v3/projects/1",
            "title": "Lorem"
          },
          "status": {
            "href": "/api/v3/project_statuses/on_track",
            "title": "On track"
          },
          "versions": {
            "href": "/api/v3/projects/1/versions"
          }
        },
        "_type": "Project",
        "active": true,
        "createdAt": "2014-05-21T08:51:20Z",
        "description": {
          "format": "markdown",
          "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>",
          "raw": "Lorem **ipsum** dolor sit amet"
        },
        "id": 1,
        "identifier": "project_identifier",
        "name": "Project example",
        "statusExplanation": {
          "format": "markdown",
          "html": "<p>Everything <strong>fine</strong></p>",
          "raw": "Everything **fine**"
        },
        "updatedAt": "2014-05-21T08:51:20Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/versions/2/projects"
    }
  },
  "_type": "Collection",
  "count": 1,
  "total": 1
}

List_projects_by_versionModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/versions/2/projects"
      }
    },
    "total": 1,
    "count": 1,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/1",
              "title": "Lorem"
            },
            "categories": {
              "href": "/api/v3/projects/1/categories"
            },
            "versions": {
              "href": "/api/v3/projects/1/versions"
            },
            "status": {
              "href": "/api/v3/project_statuses/on_track",
              "title": "On track"
            }
          },
          "id": 1,
          "identifier": "project_identifier",
          "name": "Project example",
          "description": {
            "format": "markdown",
            "raw": "Lorem **ipsum** dolor sit amet",
            "html": "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
          },
          "active": true,
          "statusExplanation": {
            "format": "markdown",
            "raw": "Everything **fine**",
            "html": "<p>Everything <strong>fine</strong></p>"
          },
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        }
      ]
    }
  }
}

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 given 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.