API: Projects
Projects are one of the types of workspaces in OpenProject structuring the information (e.g. work packages, wikis) into smaller sets. 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.
Prior to OpenProject 17.0, only projects existed and the concept of workspaces wasn’t implemented in the API. With 17.0 the other workspace types (program and portfolio) exist and might be returned in places where before, only projects were.
Actions
| Link | Description | Condition |
|---|---|---|
| update | Form endpoint that aids in updating this project | Permission: edit workspace |
| updateImmediately | Directly update this project | Permission: edit workspace |
| delete | Delete this project | Permission: admin |
| favor | Mark this project as favorited by the current user | Permission: none but login is required, only present if the project is not yet favorited |
| disfavor | Mark this project as no longer favorited by the current user | Permission: none but login is required, only present if the project is favorited |
| 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 | |
| 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 any permission 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 workspace | |
| 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 workspace |
Depending on custom fields defined for projects, additional links might exist.
Note, that the parent and ancestor links may contain the “undisclosed uri” urn:openproject-org:api:v3:undisclosed in case an ancestor 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 | |
| favorited | Indicates whether the project is favorited by the current user | Boolean | READ | |
| 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
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."
}
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 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. Prior to OpenProject 17.0, only projects existed and the concept of workspaces wasn’t implemented in the API. With 17.0 the other workspace types (program and portfolio) exist and will be returned alongside projects by this endpoint. This might surprise typed clients.
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 its own ancestor.
- available_project_attributes: filters projects based on the activated project project attributes.
- created_at: based on the time the project was created
- favorited: based on the favorited property of the project
- id: based on projects’ id.
- 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.
- project_phase_any: based on the project phases active in a project.
- project_status_code: based on status code 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.
- 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.
Each defined lifecycle step will also define a filter in this list endpoint. Given that the elements are not static but rather dynamically created on each OpenProject instance, a list cannot be provided. Those filters follow the schema:
- project_start_gate_[id]: a filter on a project phase’s start gate active in a project. The id is the id of the phase the gate belongs to.
- project_finish_gate_[id]: a filter on a project phase’s finish gate active in a project. The id is the id of the phase the gate belongs to.
- project_phase_[id]: a filter on a project phase active in a project. The id is the id of the phase queried for.
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
200
OK
{
"_type": "Collection",
"count": 2,
"total": 2,
"pageSize": 20,
"offset": 1,
"_embedded": {
"elements": [
{
"_hint": "Project resource shortened for brevity",
"id": 1,
"identifier": "initialproject",
"name": "DeathStar construction",
"active": true,
"public": true
},
{
"_hint": "Project resource shortened for brevity",
"id": 2,
"identifier": "mysecret",
"name": "Palpatine's secret plan",
"active": true,
"public": false
}
]
},
"_links": {
"self": {
"href": "/api/v3/projects?filters=%5B%5D&offset=1&pageSize=20"
},
"jumpTo": {
"href": "/api/v3/projects?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
"templated": true
},
"changeSize": {
"href": "/api/v3/projects?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
"templated": true
},
"representations": [
{
"href": "/projects.csv?filters=%5B%5D&offset=1&pageSize=20",
"identifier": "csv",
"type": "text/csv",
"title": "CSV"
},
{
"href": "/projects.xls?filters=%5B%5D&offset=1&pageSize=20",
"identifier": "xls",
"type": "application/vnd.ms-excel",
"title": "XLS"
}
]
}
}
ProjectCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/OffsetPaginatedCollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"allOf": [
{
"$ref": "#/components/schemas/OffsetPaginatedCollectionLinks"
},
{
"type": "object",
"properties": {
"representations": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A project collection representation in a specific file format."
}
]
}
}
}
}
]
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectModel"
}
}
}
}
}
}
]
}
400
Returned if the client sends invalid request parameters e.g. filters
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "Filters Invalid filter 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."
}
}
}
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"
},
"favorited": {
"type": "boolean",
"description": "Indicates whether the project is favorited by the current user"
},
"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 workspace"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit workspace"
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
}
]
},
"favor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as favorited by the current user\n\n# Conditions\n\nOnly present if the project is not yet favorited\n\nPermission**: none but login is required"
}
]
},
"disfavor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as not favorited by the current user\n\n# Conditions\nOnly present if the project is favorited by the current user\n\nPermission**: none but login is required"
}
]
},
"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 of the project\n\n**Resource**: Workspace\n\n# Conditions\n\n**Permission** edit workspace"
}
]
},
"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 workspace"
}
]
},
"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": "A collection of links to the ancestor workspaces.\n\n**Resource**: Workspace"
}
]
}
}
}
}
}
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/portfolios/2",
"title": "Root portfolios"
},
{
"href": "/api/v3/programs/12",
"title": "Grandparent program"
},
{
"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"
},
"favorited": {
"type": "boolean",
"description": "Indicates whether the project is favorited by the current user"
},
"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 workspace"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit workspace"
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
}
]
},
"favor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as favorited by the current user\n\n# Conditions\n\nOnly present if the project is not yet favorited\n\nPermission**: none but login is required"
}
]
},
"disfavor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as not favorited by the current user\n\n# Conditions\nOnly present if the project is favorited by the current user\n\nPermission**: none but login is required"
}
]
},
"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 of the project\n\n**Resource**: Workspace\n\n# Conditions\n\n**Permission** edit workspace"
}
]
},
"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 workspace"
}
]
},
"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": "A collection of links to the ancestor workspaces.\n\n**Resource**: Workspace"
}
]
}
}
}
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
{
"_embedded": {
"details": {
"attribute": "name"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Name can't be blank."
}
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 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 its 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, instead workspace_type parameter can be passed defining it for new project.
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
workspace_type
string
optional query
The workspace type of the new project the parent candidate is determined for. Ignored when of parameter is provided. Note that while ‘portfolio’ is supported as a type (since it is a type of Workspace), the endpoint will currently always return an empty resultset as portfolios cannot have parents.
Example:program
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 endpoint.
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{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The project collection\n\n**Resource**: ProjectCollection",
"readOnly": true
}
]
}
}
},
"_embedded": {
"type": "object",
"properties": {
"elements": {
"type": "array",
"readOnly": true,
"items": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectModel"
},
{
"$ref": "#/components/schemas/ProgramModel"
},
{
"$ref": "#/components/schemas/PortfolioModel"
}
]
},
"description": "Collection of projects"
}
}
}
}
}
]
}
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."
}
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."
}
}
}
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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
View project schema
Provides the schema describing a project resource. This endpoint is deprecated. As projects are workspaces, an equivalent schema can be found fetching /api/v3/workspaces/schema.
No parameters
200
OK
{
"_dependencies": [],
"_attributeGroups": [
{
"_type": "ProjectFormCustomFieldSection",
"name": "Project Details",
"attributes": [
"customField30",
"customField34"
]
},
{
"_type": "ProjectFormCustomFieldSection",
"name": "Budget Information",
"attributes": [
"customField31",
"customField32",
"customField35"
]
}
],
"_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
}
}
Workspaces_schemaModel{
"type": "object",
"description": "A schema for a workspace. This schema defines the attributes of a workspace.",
"properties": {
"_type": {
"type": "string",
"enum": [
"Schema"
],
"description": "The type identifier for this resource"
},
"_dependencies": {
"type": "array",
"description": "Schema dependencies (currently empty for workspaces)"
},
"_attributeGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_type": {
"type": "string",
"enum": [
"ProjectFormCustomFieldSection"
],
"description": "The type identifier for this resource"
},
"id": {
"type": "integer",
"description": "The unique identifier of the custom field section"
},
"name": {
"type": "string",
"description": "The human-readable name of the custom field section"
},
"attributes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of camelCase custom field attribute names belonging to this section.\nOnly includes custom fields visible to the current user."
}
}
},
"description": "Defines the organizational structure of project custom fields into sections for UI rendering.\n\nEach attribute group represents a project attribute section containing related project attributes.\nThe sections determine how project attributes are visually organized and grouped in forms.\n\n**Key behaviors:**\n- Admin-only project attributes appear only for users with admin privileges\n- Empty sections (with no accessible project attributes) are omitted from the response\n- The order reflects the configured section positioning in admin settings\n- Each section contains only project attributes assigned to that specific section\n\n**Example structure:**\n```json\n[\n {\n \"_type\": \"ProjectFormCustomFieldSection\",\n \"name\": \"Project Details\",\n \"attributes\": [\"customField1\", \"customField3\"]\n },\n {\n \"_type\": \"ProjectFormCustomFieldSection\",\n \"name\": \"Budget Information\",\n \"attributes\": [\"customField2\", \"customField4\"]\n }\n]\n```"
},
"id": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"name": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"identifier": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"description": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"public": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"active": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"status": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"statusExplanation": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"parent": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"createdAt": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"updatedAt": {
"$ref": "#/components/schemas/SchemaPropertyModel"
},
"_links": {
"type": "object",
"description": "Links related to this resource",
"properties": {
"self": {
"type": "object",
"properties": {
"href": {
"type": "string",
"example": "/api/v3/workspaces/schema"
}
}
}
}
}
},
"example": {
"_type": "Schema",
"_dependencies": [],
"_attributeGroups": [
{
"_type": "ProjectFormCustomFieldSection",
"name": "Project Details",
"attributes": "customField30 customField34"
},
{
"_type": "ProjectFormCustomFieldSection",
"name": "Budget Information",
"attributes": "customField31 customField32 customField35"
}
],
"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": "Workspace",
"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/workspaces/schema"
}
}
}
}
View project
id
integer
required path
Project id
Example:1
200
OK
{
"_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/portfolios/2",
"title": "Root portfolios"
},
{
"href": "/api/v3/programs/12",
"title": "Grandparent program"
},
{
"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"
},
"favorited": {
"type": "boolean",
"description": "Indicates whether the project is favorited by the current user"
},
"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 workspace"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit workspace"
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
}
]
},
"favor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as favorited by the current user\n\n# Conditions\n\nOnly present if the project is not yet favorited\n\nPermission**: none but login is required"
}
]
},
"disfavor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as not favorited by the current user\n\n# Conditions\nOnly present if the project is favorited by the current user\n\nPermission**: none but login is required"
}
]
},
"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 of the project\n\n**Resource**: Workspace\n\n# Conditions\n\n**Permission** edit workspace"
}
]
},
"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 workspace"
}
]
},
"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": "A collection of links to the ancestor workspaces.\n\n**Resource**: Workspace"
}
]
}
}
}
}
}
}
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."
}
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 project
Updates the given project by applying the attributes provided in the body.
id
integer
required path
Project id
Example:1
{
"_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"
},
"favorited": {
"type": "boolean",
"description": "Indicates whether the project is favorited by the current user"
},
"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 workspace"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit workspace"
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
}
]
},
"favor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as favorited by the current user\n\n# Conditions\n\nOnly present if the project is not yet favorited\n\nPermission**: none but login is required"
}
]
},
"disfavor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as not favorited by the current user\n\n# Conditions\nOnly present if the project is favorited by the current user\n\nPermission**: none but login is required"
}
]
},
"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 of the project\n\n**Resource**: Workspace\n\n# Conditions\n\n**Permission** edit workspace"
}
]
},
"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 workspace"
}
]
},
"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": "A collection of links to the ancestor workspaces.\n\n**Resource**: Workspace"
}
]
}
}
}
}
}
200
OK
{
"_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/portfolios/2",
"title": "Root portfolios"
},
{
"href": "/api/v3/programs/12",
"title": "Grandparent program"
},
{
"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"
},
"favorited": {
"type": "boolean",
"description": "Indicates whether the project is favorited by the current user"
},
"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 workspace"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Directly update this project\n\n# Conditions\n\n**Permission**: edit workspace"
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this project\n\n# Conditions\n\n**Permission**: admin"
}
]
},
"favor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as favorited by the current user\n\n# Conditions\n\nOnly present if the project is not yet favorited\n\nPermission**: none but login is required"
}
]
},
"disfavor": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Mark this project as not favorited by the current user\n\n# Conditions\nOnly present if the project is favorited by the current user\n\nPermission**: none but login is required"
}
]
},
"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 of the project\n\n**Resource**: Workspace\n\n# Conditions\n\n**Permission** edit workspace"
}
]
},
"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 workspace"
}
]
},
"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": "A collection of links to the ancestor workspaces.\n\n**Resource**: Workspace"
}
]
}
}
}
}
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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."
}
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 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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
{
"_embedded": {
"details": {
"attribute": "name"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Name can't be blank."
}
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."
}
}
}
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 endpoint to query for the actual deletion status. Such an endpoint 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."
}
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 project does not exist or the client does not have sufficient permissions to see it.
Required permission: any permission in the 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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if the project cannot be deleted. This can happen when there are still references to the project in other workspaces 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."
}
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."
}
}
}
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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
{
"_embedded": {
"details": {
"attribute": "name"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Name can't be blank."
}
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."
}
}
}
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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Favorite project
Adds the project to the current user’s favorites.
This endpoint is deprecated and replaced by /api/v3/workspaces/{id}/favorite
id
integer
required path
Project id
Example:1
204
Returned if the project was successfully added to favorites.
404
Returned if the project does not exist or the client does not have sufficient permissions to see it.
Required permission: view project
{
"_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."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: logged in
{
"_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."
}
}
}
Unfavorite project
Removes the project from the current user’s favorites.
This endpoint is deprecated and replaced by /api/v3/workspaces/{id}/favorite
id
integer
required path
Project id
Example:1
204
Returned if the project was successfully removed from favorites.
404
Returned if the project does not exist or the client does not have sufficient permissions to see it.
Required permission: view project
{
"_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."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: logged in
{
"_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."
}
}
}
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."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: edit projects in the project
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
List projects having 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.
This endpoint is deprecated and replaced by /api/v3/versions/{id}/workspaces
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:20.396Z",
"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:20.396Z"
}
]
},
"_links": {
"self": {
"href": "/api/v3/versions/2/projects"
}
},
"_type": "Collection",
"count": 1,
"total": 1
}
List_workspaces_by_versionModel{
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/versions/2/workspaces"
}
},
"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:20.142Z",
"updatedAt": "2014-05-21T08:51:20.142Z"
}
]
}
}
}
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.
List workspaces having version
This endpoint lists the workspaces where the given version is available.
The workspaces returned depend on the sharing settings of the given version, but are also limited to the workspaces 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:20.396Z",
"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:20.396Z"
}
]
},
"_links": {
"self": {
"href": "/api/v3/versions/2/projects"
}
},
"_type": "Collection",
"count": 1,
"total": 1
}
List_workspaces_by_versionModel{
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/versions/2/workspaces"
}
},
"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:20.142Z",
"updatedAt": "2014-05-21T08:51:20.142Z"
}
]
}
}
}
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 workspace 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.
