API: Work Packages

Actions

Link Description Condition
addAttachment Attach a file to the WP Permission: edit work package
addComment Post comment to WP Permission: add work package notes
addRelation Adds a relation to this work package. Permission: manage wp relations
addWatcher Add any user to WP watchers Permission: add watcher
customActions Collection of predefined changes that can be applied to the work package
logTime Log time on the work package Permission: Log time, Log own time
previewMarkup Post markup (in markdown) here to receive an HTML-rendered response
removeWatcher Remove any user from WP watchers Permission: delete watcher
unwatch Remove current user from WP watchers logged in; watching
update Form endpoint that aids in preparing and performing edits on a WP Permission: edit work package
updateImmediately Directly perform edits on a work package Permission: edit work package
watch Add current user to WP watchers logged in; not watching

Linked Properties

Link Description Type Constraints Supported operations Condition
self This work package WorkPackage not null READ
schema The schema of this work package Schema not null READ
ancestors Array of all visible ancestors of the work package, with the root node being the first element Collection not null READ Permission view work packages
attachments The files attached to this work package Collection not null READ / WRITE
author The person that created the work package User not null READ
assignee The person that is intended to work on the work package User READ / WRITE
availableWatchers All users that can be added to the work package as watchers. User READ Permission add work package watchers
budget The budget this work package is associated to Budget READ / WRITE Permission view cost objects
category The category of the work package Category READ / WRITE
children Array of all visible children of the work package Collection not null READ Permission view work packages
parent Parent work package WorkPackage Needs to be visible (to the current user) READ / WRITE
priority The priority of the work package Priority not null READ / WRITE
project The project to which the work package belongs Project not null READ / WRITE
responsible The person that is responsible for the overall outcome User READ / WRITE
relations Relations this work package is involved in Relation READ Permission view work packages
revisions Revisions that are referencing the work package Revision READ Permission view changesets
status The current status of the work package Status not null READ / WRITE
timeEntries All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change. N/A READ Permission view time entries
type The type of the work package Type not null READ / WRITE
version The version associated to the work package Version READ / WRITE
watchers All users that are currently watching this work package Collection READ Permission view work package watchers

Local Properties

Property Description Type Constraints Supported operations Condition
id Work package id Integer x > 0 READ
lockVersion The version of the item as used for optimistic locking Integer READ
subject Work package subject String not null; 1 <= length <= 255 READ / WRITE
type Name of the work package’s type String not null READ
description The work package description Formattable READ / WRITE
scheduleManually If false (default) schedule automatically. Boolean READ / WRITE
startDate Scheduled beginning of a work package Date Cannot be set for parent work packages unless it is scheduled manually; must be equal or greater than the earliest possible start date; Exists only on work packages of a non milestone type READ / WRITE
dueDate Scheduled end of a work package Date Cannot be set for parent work packages unless it is scheduled manually; must be greater than or equal to the start date; Exists only on work packages of a non milestone type READ / WRITE
date Date on which a milestone is achieved Date Exists only on work packages of a milestone type READ / WRITE
derivedStartDate Similar to start date but is not set by a client but rather deduced by the work packages’ descendants. If manual scheduleManually is active, the two dates can deviate. Date READ
derivedDueDate Similar to due date but is not set by a client but rather deduced by the work packages’ descendants. If manual scheduleManually is active, the two dates can deviate. Date READ
duration The amount of time in hours the work package needs to be completed. Duration Not available for milestone type of work packages. READ / WRITE
estimatedTime Time a work package likely needs to be completed excluding its descendants Duration READ / WRITE
derivedEstimatedTime Time a work package likely needs to be completed including its descendants Duration READ
ignoreNonWorkingDays When scheduling, whether or not to ignore the non working days being defined. A work package with the flag set to true will be allowed to be scheduled to a non working day. Boolean Cannot be set for parent work packages unless it is scheduled manually READ
spentTime The time booked for this work package by users working on it Duration READ Permission view time entries
percentageDone Amount of total completion for a work package Integer 0 <= x <= 100; Cannot be set for parent work packages READ / WRITE
readonly If true, the work package is in a readonly status so with the exception of the status, no other property can be altered. Boolean READ Enterprise edition only
createdAt Time of creation DateTime READ
updatedAt Time of the most recent change to the work package DateTime READ

Note that the properties listed here only cover the built-in properties of the OpenProject Core. Using plug-ins and custom fields a work package might contain various additional properties. A client can consult the schema information to which the work package links. The schema will contain information about all properties of the linking work package, including properties added by plug-ins and custom fields.

Custom fields are identified by a key in the form of customFieldN, where N is an integer. Depending on their type, they can occur as properties or as linked properties. A client has to consult the schema to resolve the human readable name of custom fields.

Properties that cannot be set directly on parent work packages are inferred from their children instead:

  • startDate is the earliest start date from its children if manual scheduling is activated.

  • dueDate is the latest finish date from its children if manual scheduling is activated.

  • estimatedTime is the sum of estimated times from its children

  • percentageDone is the weighted average of the sum of its children percentages done. The weight is given by the average of its children estimatedHours. However, if the percentage done is given by a work package’s status, then only the status matters and no value is inferred.

startDate can also not be earlier than a finish date of any predecessor.

While attachments are returned as a link which’s content is to be fetched separately, clients can choose to replace the work package’s attachments by providing an array of already uploaded Attachment resources on create and update. The attachments the work package has had prior to the request will be removed.

Methods

Available assignees

Gets a list of users that can be assigned to work packages in the given project.

id
integer

required path

Project id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/1",
            "method": "DELETE",
            "title": "Delete j.sheppard"
          },
          "lock": {
            "href": "/api/v3/users/1/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard"
          },
          "self": {
            "href": "/api/v3/users/1",
            "title": "John Sheppard - j.sheppard"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.com",
        "firstName": "John",
        "id": 1,
        "lastName": "Sheppard",
        "login": "j.sheppard",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      },
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/2",
            "method": "DELETE",
            "title": "Delete j.sheppard2"
          },
          "lock": {
            "href": "/api/v3/users/2/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard2"
          },
          "self": {
            "href": "/api/v3/users/2",
            "title": "Jim Sheppard - j.sheppard2"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.net",
        "firstName": "Jim",
        "id": 2,
        "lastName": "Sheppard",
        "login": "j.sheppard2",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/42/available_assignees"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Available_AssigneesModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects/42/available_assignees"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/1",
              "title": "John Sheppard - j.sheppard"
            },
            "lock": {
              "href": "/api/v3/users/1/lock",
              "title": "Set lock on j.sheppard",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/1",
              "title": "Delete j.sheppard",
              "method": "DELETE"
            }
          },
          "id": 1,
          "login": "j.sheppard",
          "firstName": "John",
          "lastName": "Sheppard",
          "email": "shep@mail.com",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        },
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/2",
              "title": "Jim Sheppard - j.sheppard2"
            },
            "lock": {
              "href": "/api/v3/users/2/lock",
              "title": "Set lock on j.sheppard2",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/2",
              "title": "Delete j.sheppard2",
              "method": "DELETE"
            }
          },
          "id": 2,
          "login": "j.sheppard2",
          "firstName": "Jim",
          "lastName": "Sheppard",
          "email": "shep@mail.net",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages

Note that you will only receive this error, if you are at least allowed to see the corresponding project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the assignable users for this project."
}
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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified project does not exist."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Available responsibles

Gets a list of users that can be assigned as the responsible of a work package in the given project.

id
integer

required path

Project id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/1",
            "method": "DELETE",
            "title": "Delete j.sheppard"
          },
          "lock": {
            "href": "/api/v3/users/1/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard"
          },
          "self": {
            "href": "/api/v3/users/1",
            "title": "John Sheppard - j.sheppard"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.com",
        "firstName": "John",
        "id": 1,
        "lastName": "Sheppard",
        "login": "j.sheppard",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      },
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/2",
            "method": "DELETE",
            "title": "Delete j.sheppard2"
          },
          "lock": {
            "href": "/api/v3/users/2/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard2"
          },
          "self": {
            "href": "/api/v3/users/2",
            "title": "Jim Sheppard - j.sheppard2"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.net",
        "firstName": "Jim",
        "id": 2,
        "lastName": "Sheppard",
        "login": "j.sheppard2",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/42/available_responsibles"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Available_ResponsiblesModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects/42/available_responsibles"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/1",
              "title": "John Sheppard - j.sheppard"
            },
            "lock": {
              "href": "/api/v3/users/1/lock",
              "title": "Set lock on j.sheppard",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/1",
              "title": "Delete j.sheppard",
              "method": "DELETE"
            }
          },
          "id": 1,
          "login": "j.sheppard",
          "firstName": "John",
          "lastName": "Sheppard",
          "email": "shep@mail.com",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        },
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/2",
              "title": "Jim Sheppard - j.sheppard2"
            },
            "lock": {
              "href": "/api/v3/users/2/lock",
              "title": "Set lock on j.sheppard2",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/2",
              "title": "Delete j.sheppard2",
              "method": "DELETE"
            }
          },
          "id": 2,
          "login": "j.sheppard2",
          "firstName": "Jim",
          "lastName": "Sheppard",
          "email": "shep@mail.net",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages

Note that you will only receive this error, if you are at least allowed to see the corresponding project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the users available as responsible for this project."
}
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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified project does not exist."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Get work packages of project

Returns the collection of work packages that are related to the given project.

id
integer

required path

Project id

Example:
1

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. If no filter is to be applied, the client should send an empty array ([]).

Default:
[{ "status_id": { "operator": "o", "values": null }}]

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

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

Default:
[["id", "asc"]]

Example:
[["status", "asc"]]

groupBy
string

optional query

The column to group by.

Example:
status

showSums
boolean

optional query

Indicates whether properties should be summed up if they support it.

Default:
false

Example:
true

select
string

optional query

Comma separated list of properties to include.

Example:
total,elements/subject,elements/id,self

200

OK

Work_PackagesModel 
{
  "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 work package collection\n\n**Resource**: WorkPackageCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Work_PackageModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_hint": "Work package resource shortened for brevity",
          "_type": "WorkPackage",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/1"
            }
          },
          "id": 1
        },
        {
          "_hint": "Work package resource shortened for brevity",
          "_type": "WorkPackage",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/2"
            }
          },
          "id": 2
        }
      ]
    }
  }
}

400

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages

Note that you will only receive this error, if you are at least allowed to see the corresponding project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the work packages of this project."
}
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

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified project does not exist."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create work package in project

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

id
integer

required path

Project id

Example:
1

notify
boolean

optional query

Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

Default:
true

Example:
false

200

OK

Work_PackageModel 
{
  "type": "object",
  "required": [
    "subject",
    "_links"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Work package id",
      "readOnly": true,
      "minimum": 1
    },
    "lockVersion": {
      "type": "integer",
      "description": "The version of the item as used for optimistic locking",
      "readOnly": true
    },
    "subject": {
      "type": "string",
      "description": "Work package subject"
    },
    "_type": {
      "type": "string",
      "enum": [
        "WorkPackage"
      ],
      "readOnly": true
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "The work package description"
        }
      ]
    },
    "scheduleManually": {
      "type": "boolean",
      "description": "If false (default) schedule automatically."
    },
    "readonly": {
      "type": "boolean",
      "description": "If true, the work package is in a readonly status so with the exception of the status, no other property can be altered."
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled beginning of a work package"
    },
    "dueDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled end of a work package"
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Date on which a milestone is achieved"
    },
    "derivedStartDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to start date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "derivedDueDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to due date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "duration": {
      "type": "string",
      "format": "duration",
      "description": "**(NOT IMPLEMENTED)** The amount of time in hours the work package needs to be completed.\nNot available for milestone type of work packages.",
      "readOnly": true
    },
    "estimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed excluding its descendants"
    },
    "derivedEstimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed including its descendants",
      "readOnly": true
    },
    "ignoreNonWorkingDays": {
      "type": "boolean",
      "description": "**(NOT IMPLEMENTED)** When scheduling, whether or not to ignore the non working days being defined.\nA work package with the flag set to true will be allowed to be scheduled to a non working day.",
      "readOnly": true
    },
    "spentTime": {
      "type": "string",
      "format": "duration",
      "description": "The time booked for this work package by users working on it\n\n# Conditions\n\n**Permission** view time entries",
      "readOnly": true
    },
    "percentageDone": {
      "type": "integer",
      "description": "Amount of total completion for a work package",
      "maximum": 100
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the work package",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "ancestors",
        "attachments",
        "author",
        "children",
        "priority",
        "project",
        "status",
        "type"
      ],
      "properties": {
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Attach a file to the WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "addComment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post comment to WP\n\n# Conditions\n\n**Permission**: add work package notes",
              "readOnly": true
            }
          ]
        },
        "addRelation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Adds a relation to this work package.\n\n# Conditions\n\n**Permission**: manage wp relations",
              "readOnly": true
            }
          ]
        },
        "addWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add any user to WP watchers\n\n# Conditions\n\n**Permission**: add watcher",
              "readOnly": true
            }
          ]
        },
        "customActions": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A predefined action that can be applied to the work package.\n\n**Resource**: CustomAction",
                "readOnly": true
              }
            ]
          }
        },
        "previewMarkup": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post markup (in markdown) here to receive an HTML-rendered response",
              "readOnly": true
            }
          ]
        },
        "removeWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove any user from WP watchers\n\n# Conditions\n\n**Permission**: delete watcher",
              "readOnly": true
            }
          ]
        },
        "unwatch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove current user from WP watchers\n\n# Conditions\n\nlogged in; watching",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Form endpoint that aids in preparing and performing edits on a WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on a work package\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "watch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add current user to WP watchers\n\n# Conditions\n\nlogged in; not watching",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This work package\n\n**Resource**: WorkPackage",
              "readOnly": true
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema of this work package\n\n**Resource**: Schema",
              "readOnly": true
            }
          ]
        },
        "ancestors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible ancestor work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The files attached to this work package\n\n**Resource**: Collection"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that created the work package\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "assignee": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is intended to work on the work package\n\n**Resource**: User"
            }
          ]
        },
        "availableWatchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that can be added to the work package as watchers.\n\n**Resource**: User\n\n# Conditions\n\n**Permission** add work package watchers",
              "readOnly": true
            }
          ]
        },
        "budget": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The budget this work package is associated to\n\n**Resource**: Budget\n\n# Conditions\n\n**Permission** view cost objects"
            }
          ]
        },
        "category": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The category of the work package\n\n**Resource**: Category"
            }
          ]
        },
        "children": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible child work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "addFileLink": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add a file link to the work package\n\n# Conditions\n\n**Permission**: manage file links"
            }
          ]
        },
        "fileLinks": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Gets the file link collection of this work package\n\n# Conditions\n\n**Permission**: view file links"
            }
          ]
        },
        "parent": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Parent work package\n\n**Resource**: WorkPackage"
            }
          ]
        },
        "priority": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The priority of the work package\n\n**Resource**: Priority"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project to which the work package belongs\n\n**Resource**: Project"
            }
          ]
        },
        "responsible": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is responsible for the overall outcome\n\n**Resource**: User"
            }
          ]
        },
        "relations": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Relations this work package is involved in\n\n**Resource**: Relation\n\n# Conditions\n\n**Permission** view work packages",
              "readOnly": true
            }
          ]
        },
        "revisions": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Revisions that are referencing the work package\n\n**Resource**: Revision\n\n# Conditions\n\n**Permission** view changesets",
              "readOnly": true
            }
          ]
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The current status of the work package\n\n**Resource**: Status"
            }
          ]
        },
        "timeEntries": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.\n\n**Resource**: N/A\n\n# Conditions\n\n**Permission** view time entries",
              "readOnly": true
            }
          ]
        },
        "type": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The type of the work package\n\n**Resource**: Type"
            }
          ]
        },
        "version": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The version associated to the work package\n\n**Resource**: Version"
            }
          ]
        },
        "watchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that are currently watching this work package\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission** view work package watchers",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "WorkPackage",
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/1528",
        "title": "Develop API"
      },
      "schema": {
        "href": "/api/v3/work_packages/schemas/11-2"
      },
      "update": {
        "href": "/api/v3/work_packages/1528",
        "method": "patch",
        "title": "Update Develop API"
      },
      "delete": {
        "href": "/work_packages/bulk?ids=1528",
        "method": "delete",
        "title": "Delete Develop API"
      },
      "logTime": {
        "href": "/work_packages/1528/time_entries/new",
        "type": "text/html",
        "title": "Log time on Develop API"
      },
      "move": {
        "href": "/work_packages/1528/move/new",
        "type": "text/html",
        "title": "Move Develop API"
      },
      "attachments": {
        "href": "/api/v3/work_packages/1528/attachments"
      },
      "addAttachment": {
        "href": "/api/v3/work_packages/1528/attachments",
        "method": "post"
      },
      "author": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin - admin"
      },
      "customActions": [
        {
          "href": "/api/v3/work_packages/1528/custom_actions/153/execute",
          "method": "post",
          "title": "Reset"
        },
        {
          "href": "/api/v3/work_packages/1528/custom_actions/94/execute",
          "method": "post",
          "title": "Forward to accounting"
        }
      ],
      "responsible": {
        "href": "/api/v3/users/23",
        "title": "Laron Leuschke - Alaina5788"
      },
      "relations": {
        "href": "/api/v3/work_packages/1528/relations",
        "title": "Show relations"
      },
      "revisions": {
        "href": "/api/v3/work_packages/1528/revisions"
      },
      "assignee": {
        "href": "/api/v3/users/11",
        "title": "Emmie Okuneva - Adele5450"
      },
      "priority": {
        "href": "/api/v3/priorities/2",
        "title": "Normal"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A Test Project"
      },
      "status": {
        "href": "/api/v3/statuses/1",
        "title": "New"
      },
      "type": {
        "href": "/api/v3/types/1",
        "title": "A Type"
      },
      "version": {
        "href": "/api/v3/versions/1",
        "title": "Version 1"
      },
      "availableWatchers": {
        "href": "/api/v3/work_packages/1528/available_watchers"
      },
      "watch": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/1"
          }
        }
      },
      "addWatcher": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/{user_id}"
          }
        },
        "templated": true
      },
      "removeWatcher": {
        "href": "/api/v3/work_packages/1528/watchers/{user_id}",
        "method": "delete",
        "templated": true
      },
      "addRelation": {
        "href": "/api/v3/relations",
        "method": "post",
        "title": "Add relation"
      },
      "changeParent": {
        "href": "/api/v3/work_packages/694",
        "method": "patch",
        "title": "Change parent of Bug in OpenProject"
      },
      "addComment": {
        "href": "/api/v3/work_packages/1528/activities",
        "method": "post",
        "title": "Add comment"
      },
      "parent": {
        "href": "/api/v3/work_packages/1298",
        "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
      },
      "category": {
        "href": "/api/v3/categories/1298",
        "title": "eligend isi"
      },
      "children": [
        {
          "href": "/api/v3/work_packages/1529",
          "title": "Write API documentation"
        }
      ],
      "ancestors": [
        {
          "href": "/api/v3/work_packages/1290",
          "title": "Root node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1291",
          "title": "Intermediate node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        }
      ],
      "timeEntries": {
        "href": "/work_packages/1528/time_entries",
        "type": "text/html",
        "title": "Time entries"
      },
      "watchers": {
        "href": "/api/v3/work_packages/1528/watchers"
      },
      "customField3": {
        "href": "api/v3/users/14"
      }
    },
    "id": 1528,
    "subject": "Develop API",
    "description": {
      "format": "markdown",
      "raw": "Develop super cool OpenProject API.",
      "html": "<p>Develop super cool OpenProject API.</p>"
    },
    "scheduleManually": false,
    "readonly": false,
    "startDate": null,
    "dueDate": null,
    "derivedStartDate": null,
    "derivedDueDate": null,
    "estimatedTime": "PT2H",
    "derivedEstimatedTime": "PT10H",
    "percentageDone": 0,
    "customField1": "Foo",
    "customField2": 42,
    "createdAt": "2014-08-29T12:40:53Z",
    "updatedAt": "2014-08-29T12:44:41Z"
  }
}

400

403

Returned if the client does not have sufficient permissions.

Required permission: add work packages

Note that you will only receive this error, if you are at least allowed to see the corresponding project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to add work packages to this project."
}
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 permissions: 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 specified project does not exist."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

415

422

Returned if:

  • the client tries to write a read-only property

  • a constraint for a property was violated

  • a property was provided in an unreadable format

{
  "_embedded": {
    "details": {
      "attribute": "Subject"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The subject might not 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."
    }
  }
}

Work package create form for project

id
integer

required path

ID of the project in which the work package will be created

Example:
1

200

OK

List work packages

Returns a collection of work packages.

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. If no filter is to be applied, the client should send an empty array ([]), otherwise a default filter is applied. A Currently supported filters are (there are additional filters added by modules):

  • assigned_to
  • assignee_or_group
  • attachment_base
  • attachment_content
  • attachment_file_name
  • author
  • blocked
  • blocks
  • category
  • comment
  • created_at
  • custom_field
  • dates_interval
  • description
  • done_ratio
  • due_date
  • duplicated
  • duplicates
  • duration
  • estimated_hours
  • file_link_origin_id
  • follows
  • group
  • id
  • includes
  • linkable_to_storage_id
  • linkable_to_storage_url
  • manual_sort
  • milestone
  • only_subproject
  • parent
  • partof
  • precedes
  • principal_base
  • priority
  • project
  • relatable
  • relates
  • required
  • requires
  • responsible
  • role
  • search
  • start_date
  • status
  • storage_id
  • storage_url
  • subject
  • subject_or_id
  • subproject
  • type
  • typeahead
  • updated_at
  • version
  • watcher
  • work_package

Default:
[{ "status_id": { "operator": "o", "values": null }}]

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

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

Default:
[["id", "asc"]]

Example:
[["status", "asc"]]

groupBy
string

optional query

The column to group by.

Example:
status

showSums
boolean

optional query

Indicates whether properties should be summed up if they support it.

Default:
false

Example:
true

select
string

optional query

Comma separated list of properties to include.

Example:
total,elements/subject,elements/id,self

timestamps
string

optional query

In order to perform a baseline comparison, you may provide one or several timestamps in ISO-8601 format as comma-separated list. The timestamps may be absolute or relative. Usually, the first timestamp is the baseline date, the last timestamp is the current date.

Default:
PT0S

Example:
2022-01-01T00:00:00Z,PT0S

200

OK

Work_PackagesModel 
{
  "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 work package collection\n\n**Resource**: WorkPackageCollection",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Work_PackageModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_hint": "Work package resource shortened for brevity",
          "_type": "WorkPackage",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/1"
            }
          },
          "id": 1
        },
        {
          "_hint": "Work package resource shortened for brevity",
          "_type": "WorkPackage",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/2"
            }
          },
          "id": 2
        }
      ]
    }
  }
}

400

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages (globally or in any project)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see work packages."
}
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 work package

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a WorkPackage can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

A project link must be set when creating work packages through this route.

When setting start date, finish date, and duration together, their correctness will be checked and a 422 error will be returned if one value does not match with the two others. You can make the server compute a value: set only two values in the request and the third one will be computed and returned in the response. For instance, when sending { "startDate": "2022-08-23", duration: "P2D" }, the response will include { "dueDate": "2022-08-24" }.

notify
boolean

optional query

Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

Default:
true

Example:
false

200

OK

Work_PackageModel 
{
  "type": "object",
  "required": [
    "subject",
    "_links"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Work package id",
      "readOnly": true,
      "minimum": 1
    },
    "lockVersion": {
      "type": "integer",
      "description": "The version of the item as used for optimistic locking",
      "readOnly": true
    },
    "subject": {
      "type": "string",
      "description": "Work package subject"
    },
    "_type": {
      "type": "string",
      "enum": [
        "WorkPackage"
      ],
      "readOnly": true
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "The work package description"
        }
      ]
    },
    "scheduleManually": {
      "type": "boolean",
      "description": "If false (default) schedule automatically."
    },
    "readonly": {
      "type": "boolean",
      "description": "If true, the work package is in a readonly status so with the exception of the status, no other property can be altered."
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled beginning of a work package"
    },
    "dueDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled end of a work package"
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Date on which a milestone is achieved"
    },
    "derivedStartDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to start date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "derivedDueDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to due date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "duration": {
      "type": "string",
      "format": "duration",
      "description": "**(NOT IMPLEMENTED)** The amount of time in hours the work package needs to be completed.\nNot available for milestone type of work packages.",
      "readOnly": true
    },
    "estimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed excluding its descendants"
    },
    "derivedEstimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed including its descendants",
      "readOnly": true
    },
    "ignoreNonWorkingDays": {
      "type": "boolean",
      "description": "**(NOT IMPLEMENTED)** When scheduling, whether or not to ignore the non working days being defined.\nA work package with the flag set to true will be allowed to be scheduled to a non working day.",
      "readOnly": true
    },
    "spentTime": {
      "type": "string",
      "format": "duration",
      "description": "The time booked for this work package by users working on it\n\n# Conditions\n\n**Permission** view time entries",
      "readOnly": true
    },
    "percentageDone": {
      "type": "integer",
      "description": "Amount of total completion for a work package",
      "maximum": 100
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the work package",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "ancestors",
        "attachments",
        "author",
        "children",
        "priority",
        "project",
        "status",
        "type"
      ],
      "properties": {
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Attach a file to the WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "addComment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post comment to WP\n\n# Conditions\n\n**Permission**: add work package notes",
              "readOnly": true
            }
          ]
        },
        "addRelation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Adds a relation to this work package.\n\n# Conditions\n\n**Permission**: manage wp relations",
              "readOnly": true
            }
          ]
        },
        "addWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add any user to WP watchers\n\n# Conditions\n\n**Permission**: add watcher",
              "readOnly": true
            }
          ]
        },
        "customActions": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A predefined action that can be applied to the work package.\n\n**Resource**: CustomAction",
                "readOnly": true
              }
            ]
          }
        },
        "previewMarkup": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post markup (in markdown) here to receive an HTML-rendered response",
              "readOnly": true
            }
          ]
        },
        "removeWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove any user from WP watchers\n\n# Conditions\n\n**Permission**: delete watcher",
              "readOnly": true
            }
          ]
        },
        "unwatch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove current user from WP watchers\n\n# Conditions\n\nlogged in; watching",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Form endpoint that aids in preparing and performing edits on a WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on a work package\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "watch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add current user to WP watchers\n\n# Conditions\n\nlogged in; not watching",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This work package\n\n**Resource**: WorkPackage",
              "readOnly": true
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema of this work package\n\n**Resource**: Schema",
              "readOnly": true
            }
          ]
        },
        "ancestors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible ancestor work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The files attached to this work package\n\n**Resource**: Collection"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that created the work package\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "assignee": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is intended to work on the work package\n\n**Resource**: User"
            }
          ]
        },
        "availableWatchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that can be added to the work package as watchers.\n\n**Resource**: User\n\n# Conditions\n\n**Permission** add work package watchers",
              "readOnly": true
            }
          ]
        },
        "budget": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The budget this work package is associated to\n\n**Resource**: Budget\n\n# Conditions\n\n**Permission** view cost objects"
            }
          ]
        },
        "category": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The category of the work package\n\n**Resource**: Category"
            }
          ]
        },
        "children": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible child work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "addFileLink": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add a file link to the work package\n\n# Conditions\n\n**Permission**: manage file links"
            }
          ]
        },
        "fileLinks": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Gets the file link collection of this work package\n\n# Conditions\n\n**Permission**: view file links"
            }
          ]
        },
        "parent": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Parent work package\n\n**Resource**: WorkPackage"
            }
          ]
        },
        "priority": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The priority of the work package\n\n**Resource**: Priority"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project to which the work package belongs\n\n**Resource**: Project"
            }
          ]
        },
        "responsible": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is responsible for the overall outcome\n\n**Resource**: User"
            }
          ]
        },
        "relations": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Relations this work package is involved in\n\n**Resource**: Relation\n\n# Conditions\n\n**Permission** view work packages",
              "readOnly": true
            }
          ]
        },
        "revisions": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Revisions that are referencing the work package\n\n**Resource**: Revision\n\n# Conditions\n\n**Permission** view changesets",
              "readOnly": true
            }
          ]
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The current status of the work package\n\n**Resource**: Status"
            }
          ]
        },
        "timeEntries": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.\n\n**Resource**: N/A\n\n# Conditions\n\n**Permission** view time entries",
              "readOnly": true
            }
          ]
        },
        "type": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The type of the work package\n\n**Resource**: Type"
            }
          ]
        },
        "version": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The version associated to the work package\n\n**Resource**: Version"
            }
          ]
        },
        "watchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that are currently watching this work package\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission** view work package watchers",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "WorkPackage",
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/1528",
        "title": "Develop API"
      },
      "schema": {
        "href": "/api/v3/work_packages/schemas/11-2"
      },
      "update": {
        "href": "/api/v3/work_packages/1528",
        "method": "patch",
        "title": "Update Develop API"
      },
      "delete": {
        "href": "/work_packages/bulk?ids=1528",
        "method": "delete",
        "title": "Delete Develop API"
      },
      "logTime": {
        "href": "/work_packages/1528/time_entries/new",
        "type": "text/html",
        "title": "Log time on Develop API"
      },
      "move": {
        "href": "/work_packages/1528/move/new",
        "type": "text/html",
        "title": "Move Develop API"
      },
      "attachments": {
        "href": "/api/v3/work_packages/1528/attachments"
      },
      "addAttachment": {
        "href": "/api/v3/work_packages/1528/attachments",
        "method": "post"
      },
      "author": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin - admin"
      },
      "customActions": [
        {
          "href": "/api/v3/work_packages/1528/custom_actions/153/execute",
          "method": "post",
          "title": "Reset"
        },
        {
          "href": "/api/v3/work_packages/1528/custom_actions/94/execute",
          "method": "post",
          "title": "Forward to accounting"
        }
      ],
      "responsible": {
        "href": "/api/v3/users/23",
        "title": "Laron Leuschke - Alaina5788"
      },
      "relations": {
        "href": "/api/v3/work_packages/1528/relations",
        "title": "Show relations"
      },
      "revisions": {
        "href": "/api/v3/work_packages/1528/revisions"
      },
      "assignee": {
        "href": "/api/v3/users/11",
        "title": "Emmie Okuneva - Adele5450"
      },
      "priority": {
        "href": "/api/v3/priorities/2",
        "title": "Normal"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A Test Project"
      },
      "status": {
        "href": "/api/v3/statuses/1",
        "title": "New"
      },
      "type": {
        "href": "/api/v3/types/1",
        "title": "A Type"
      },
      "version": {
        "href": "/api/v3/versions/1",
        "title": "Version 1"
      },
      "availableWatchers": {
        "href": "/api/v3/work_packages/1528/available_watchers"
      },
      "watch": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/1"
          }
        }
      },
      "addWatcher": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/{user_id}"
          }
        },
        "templated": true
      },
      "removeWatcher": {
        "href": "/api/v3/work_packages/1528/watchers/{user_id}",
        "method": "delete",
        "templated": true
      },
      "addRelation": {
        "href": "/api/v3/relations",
        "method": "post",
        "title": "Add relation"
      },
      "changeParent": {
        "href": "/api/v3/work_packages/694",
        "method": "patch",
        "title": "Change parent of Bug in OpenProject"
      },
      "addComment": {
        "href": "/api/v3/work_packages/1528/activities",
        "method": "post",
        "title": "Add comment"
      },
      "parent": {
        "href": "/api/v3/work_packages/1298",
        "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
      },
      "category": {
        "href": "/api/v3/categories/1298",
        "title": "eligend isi"
      },
      "children": [
        {
          "href": "/api/v3/work_packages/1529",
          "title": "Write API documentation"
        }
      ],
      "ancestors": [
        {
          "href": "/api/v3/work_packages/1290",
          "title": "Root node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1291",
          "title": "Intermediate node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        }
      ],
      "timeEntries": {
        "href": "/work_packages/1528/time_entries",
        "type": "text/html",
        "title": "Time entries"
      },
      "watchers": {
        "href": "/api/v3/work_packages/1528/watchers"
      },
      "customField3": {
        "href": "api/v3/users/14"
      }
    },
    "id": 1528,
    "subject": "Develop API",
    "description": {
      "format": "markdown",
      "raw": "Develop super cool OpenProject API.",
      "html": "<p>Develop super cool OpenProject API.</p>"
    },
    "scheduleManually": false,
    "readonly": false,
    "startDate": null,
    "dueDate": null,
    "derivedStartDate": null,
    "derivedDueDate": null,
    "estimatedTime": "PT2H",
    "derivedEstimatedTime": "PT10H",
    "percentageDone": 0,
    "customField1": "Foo",
    "customField2": 42,
    "createdAt": "2014-08-29T12:40:53Z",
    "updatedAt": "2014-08-29T12:44:41Z"
  }
}

400

403

Returned if the client does not have sufficient permissions.

Required permission: add work packages

Note that you will only receive this error, if you are at least allowed to see the corresponding project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to add work packages to this project."
}
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 permissions: 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 specified project does not exist."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

415

422

Returned if:

  • the client tries to write a read-only property

  • a constraint for a property was violated

  • a property was provided in an unreadable format

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The subject might not be blank.",
  "_embedded": {
    "details": {
      "attribute": "Subject"
    }
  }
}
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."
    }
  }
}

Work package create form

No parameters

200

OK

List work package schemas

List work package schemas.

filters
string

required query

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

  • id: The schema’s id

Schema id has the form project_id-work_package_type_id.

Example:
[{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/work_packages/schemas/13-1"
          }
        },
        "_type": "Schema..."
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/work_packages/schemas/7-6"
          }
        },
        "_type": "Schema..."
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/work_packages/schemas"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 5
}
Work_Package_SchemasModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/schemas"
      }
    },
    "total": 5,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "Schema...",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/schemas/13-1"
            }
          }
        },
        {
          "_type": "Schema...",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/schemas/7-6"
            }
          }
        }
      ]
    }
  }
}

400

403

Returned if the client does not have sufficient permissions.

Required permission: View work packages in any project.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to list schemas."
}
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 work package schema

identifier
string

required path

Identifier of the schema

Example:
12-13

200

OK

404

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

Required permission: view work packages (on the project where this schema is used)

Note: A client without sufficient permissions shall not be able to test for the existence of a project. That’s why a 404 is returned here, even if a 403 might be more appropriate.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified schema 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."
    }
  }
}

View work package

Returns the specified work package.

id
integer

required path

Work package id

Example:
1

timestamps
string

optional query

In order to perform a baseline comparison of the work-package attributes, you may provide one or several timestamps in ISO-8601 format as comma-separated list. The timestamps may be absolute or relative. Usually, the first timestamp is the baseline date, the last timestamp is the current date.

Default:
PT0S

Example:
2022-01-01T00:00:00Z,PT0S

200

OK

Work_PackageModel 
{
  "type": "object",
  "required": [
    "subject",
    "_links"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Work package id",
      "readOnly": true,
      "minimum": 1
    },
    "lockVersion": {
      "type": "integer",
      "description": "The version of the item as used for optimistic locking",
      "readOnly": true
    },
    "subject": {
      "type": "string",
      "description": "Work package subject"
    },
    "_type": {
      "type": "string",
      "enum": [
        "WorkPackage"
      ],
      "readOnly": true
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "The work package description"
        }
      ]
    },
    "scheduleManually": {
      "type": "boolean",
      "description": "If false (default) schedule automatically."
    },
    "readonly": {
      "type": "boolean",
      "description": "If true, the work package is in a readonly status so with the exception of the status, no other property can be altered."
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled beginning of a work package"
    },
    "dueDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled end of a work package"
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Date on which a milestone is achieved"
    },
    "derivedStartDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to start date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "derivedDueDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to due date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "duration": {
      "type": "string",
      "format": "duration",
      "description": "**(NOT IMPLEMENTED)** The amount of time in hours the work package needs to be completed.\nNot available for milestone type of work packages.",
      "readOnly": true
    },
    "estimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed excluding its descendants"
    },
    "derivedEstimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed including its descendants",
      "readOnly": true
    },
    "ignoreNonWorkingDays": {
      "type": "boolean",
      "description": "**(NOT IMPLEMENTED)** When scheduling, whether or not to ignore the non working days being defined.\nA work package with the flag set to true will be allowed to be scheduled to a non working day.",
      "readOnly": true
    },
    "spentTime": {
      "type": "string",
      "format": "duration",
      "description": "The time booked for this work package by users working on it\n\n# Conditions\n\n**Permission** view time entries",
      "readOnly": true
    },
    "percentageDone": {
      "type": "integer",
      "description": "Amount of total completion for a work package",
      "maximum": 100
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the work package",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "ancestors",
        "attachments",
        "author",
        "children",
        "priority",
        "project",
        "status",
        "type"
      ],
      "properties": {
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Attach a file to the WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "addComment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post comment to WP\n\n# Conditions\n\n**Permission**: add work package notes",
              "readOnly": true
            }
          ]
        },
        "addRelation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Adds a relation to this work package.\n\n# Conditions\n\n**Permission**: manage wp relations",
              "readOnly": true
            }
          ]
        },
        "addWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add any user to WP watchers\n\n# Conditions\n\n**Permission**: add watcher",
              "readOnly": true
            }
          ]
        },
        "customActions": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A predefined action that can be applied to the work package.\n\n**Resource**: CustomAction",
                "readOnly": true
              }
            ]
          }
        },
        "previewMarkup": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post markup (in markdown) here to receive an HTML-rendered response",
              "readOnly": true
            }
          ]
        },
        "removeWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove any user from WP watchers\n\n# Conditions\n\n**Permission**: delete watcher",
              "readOnly": true
            }
          ]
        },
        "unwatch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove current user from WP watchers\n\n# Conditions\n\nlogged in; watching",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Form endpoint that aids in preparing and performing edits on a WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on a work package\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "watch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add current user to WP watchers\n\n# Conditions\n\nlogged in; not watching",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This work package\n\n**Resource**: WorkPackage",
              "readOnly": true
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema of this work package\n\n**Resource**: Schema",
              "readOnly": true
            }
          ]
        },
        "ancestors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible ancestor work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The files attached to this work package\n\n**Resource**: Collection"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that created the work package\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "assignee": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is intended to work on the work package\n\n**Resource**: User"
            }
          ]
        },
        "availableWatchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that can be added to the work package as watchers.\n\n**Resource**: User\n\n# Conditions\n\n**Permission** add work package watchers",
              "readOnly": true
            }
          ]
        },
        "budget": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The budget this work package is associated to\n\n**Resource**: Budget\n\n# Conditions\n\n**Permission** view cost objects"
            }
          ]
        },
        "category": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The category of the work package\n\n**Resource**: Category"
            }
          ]
        },
        "children": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible child work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "addFileLink": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add a file link to the work package\n\n# Conditions\n\n**Permission**: manage file links"
            }
          ]
        },
        "fileLinks": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Gets the file link collection of this work package\n\n# Conditions\n\n**Permission**: view file links"
            }
          ]
        },
        "parent": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Parent work package\n\n**Resource**: WorkPackage"
            }
          ]
        },
        "priority": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The priority of the work package\n\n**Resource**: Priority"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project to which the work package belongs\n\n**Resource**: Project"
            }
          ]
        },
        "responsible": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is responsible for the overall outcome\n\n**Resource**: User"
            }
          ]
        },
        "relations": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Relations this work package is involved in\n\n**Resource**: Relation\n\n# Conditions\n\n**Permission** view work packages",
              "readOnly": true
            }
          ]
        },
        "revisions": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Revisions that are referencing the work package\n\n**Resource**: Revision\n\n# Conditions\n\n**Permission** view changesets",
              "readOnly": true
            }
          ]
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The current status of the work package\n\n**Resource**: Status"
            }
          ]
        },
        "timeEntries": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.\n\n**Resource**: N/A\n\n# Conditions\n\n**Permission** view time entries",
              "readOnly": true
            }
          ]
        },
        "type": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The type of the work package\n\n**Resource**: Type"
            }
          ]
        },
        "version": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The version associated to the work package\n\n**Resource**: Version"
            }
          ]
        },
        "watchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that are currently watching this work package\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission** view work package watchers",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "WorkPackage",
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/1528",
        "title": "Develop API"
      },
      "schema": {
        "href": "/api/v3/work_packages/schemas/11-2"
      },
      "update": {
        "href": "/api/v3/work_packages/1528",
        "method": "patch",
        "title": "Update Develop API"
      },
      "delete": {
        "href": "/work_packages/bulk?ids=1528",
        "method": "delete",
        "title": "Delete Develop API"
      },
      "logTime": {
        "href": "/work_packages/1528/time_entries/new",
        "type": "text/html",
        "title": "Log time on Develop API"
      },
      "move": {
        "href": "/work_packages/1528/move/new",
        "type": "text/html",
        "title": "Move Develop API"
      },
      "attachments": {
        "href": "/api/v3/work_packages/1528/attachments"
      },
      "addAttachment": {
        "href": "/api/v3/work_packages/1528/attachments",
        "method": "post"
      },
      "author": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin - admin"
      },
      "customActions": [
        {
          "href": "/api/v3/work_packages/1528/custom_actions/153/execute",
          "method": "post",
          "title": "Reset"
        },
        {
          "href": "/api/v3/work_packages/1528/custom_actions/94/execute",
          "method": "post",
          "title": "Forward to accounting"
        }
      ],
      "responsible": {
        "href": "/api/v3/users/23",
        "title": "Laron Leuschke - Alaina5788"
      },
      "relations": {
        "href": "/api/v3/work_packages/1528/relations",
        "title": "Show relations"
      },
      "revisions": {
        "href": "/api/v3/work_packages/1528/revisions"
      },
      "assignee": {
        "href": "/api/v3/users/11",
        "title": "Emmie Okuneva - Adele5450"
      },
      "priority": {
        "href": "/api/v3/priorities/2",
        "title": "Normal"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A Test Project"
      },
      "status": {
        "href": "/api/v3/statuses/1",
        "title": "New"
      },
      "type": {
        "href": "/api/v3/types/1",
        "title": "A Type"
      },
      "version": {
        "href": "/api/v3/versions/1",
        "title": "Version 1"
      },
      "availableWatchers": {
        "href": "/api/v3/work_packages/1528/available_watchers"
      },
      "watch": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/1"
          }
        }
      },
      "addWatcher": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/{user_id}"
          }
        },
        "templated": true
      },
      "removeWatcher": {
        "href": "/api/v3/work_packages/1528/watchers/{user_id}",
        "method": "delete",
        "templated": true
      },
      "addRelation": {
        "href": "/api/v3/relations",
        "method": "post",
        "title": "Add relation"
      },
      "changeParent": {
        "href": "/api/v3/work_packages/694",
        "method": "patch",
        "title": "Change parent of Bug in OpenProject"
      },
      "addComment": {
        "href": "/api/v3/work_packages/1528/activities",
        "method": "post",
        "title": "Add comment"
      },
      "parent": {
        "href": "/api/v3/work_packages/1298",
        "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
      },
      "category": {
        "href": "/api/v3/categories/1298",
        "title": "eligend isi"
      },
      "children": [
        {
          "href": "/api/v3/work_packages/1529",
          "title": "Write API documentation"
        }
      ],
      "ancestors": [
        {
          "href": "/api/v3/work_packages/1290",
          "title": "Root node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1291",
          "title": "Intermediate node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        }
      ],
      "timeEntries": {
        "href": "/work_packages/1528/time_entries",
        "type": "text/html",
        "title": "Time entries"
      },
      "watchers": {
        "href": "/api/v3/work_packages/1528/watchers"
      },
      "customField3": {
        "href": "api/v3/users/14"
      }
    },
    "id": 1528,
    "subject": "Develop API",
    "description": {
      "format": "markdown",
      "raw": "Develop super cool OpenProject API.",
      "html": "<p>Develop super cool OpenProject API.</p>"
    },
    "scheduleManually": false,
    "readonly": false,
    "startDate": null,
    "dueDate": null,
    "derivedStartDate": null,
    "derivedDueDate": null,
    "estimatedTime": "PT2H",
    "derivedEstimatedTime": "PT10H",
    "percentageDone": 0,
    "customField1": "Foo",
    "customField2": 42,
    "createdAt": "2014-08-29T12:40:53Z",
    "updatedAt": "2014-08-29T12:44:41Z"
  }
}

404

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

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

Edit work package

When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. Note that it is only allowed to provide properties or links supporting the write operation.

Additionally to the fields the client wants to change, it is mandatory to provide the value of lockVersion which was received by the GET request this change originates from.

The value of lockVersion is used to implement optimistic locking.

id
integer

required path

Work package id

Example:
1

notify
boolean

optional query

Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

Default:
true

Example:
false

200

OK

Work_PackageModel 
{
  "type": "object",
  "required": [
    "subject",
    "_links"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Work package id",
      "readOnly": true,
      "minimum": 1
    },
    "lockVersion": {
      "type": "integer",
      "description": "The version of the item as used for optimistic locking",
      "readOnly": true
    },
    "subject": {
      "type": "string",
      "description": "Work package subject"
    },
    "_type": {
      "type": "string",
      "enum": [
        "WorkPackage"
      ],
      "readOnly": true
    },
    "description": {
      "allOf": [
        {
          "$ref": "#/components/schemas/Formattable"
        },
        {
          "description": "The work package description"
        }
      ]
    },
    "scheduleManually": {
      "type": "boolean",
      "description": "If false (default) schedule automatically."
    },
    "readonly": {
      "type": "boolean",
      "description": "If true, the work package is in a readonly status so with the exception of the status, no other property can be altered."
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled beginning of a work package"
    },
    "dueDate": {
      "type": "string",
      "format": "date",
      "description": "Scheduled end of a work package"
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Date on which a milestone is achieved"
    },
    "derivedStartDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to start date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "derivedDueDate": {
      "type": "string",
      "format": "date",
      "description": "Similar to due date but is not set by a client but rather deduced by the work packages' descendants. If manual scheduleManually is active, the two dates can deviate.",
      "readOnly": true
    },
    "duration": {
      "type": "string",
      "format": "duration",
      "description": "**(NOT IMPLEMENTED)** The amount of time in hours the work package needs to be completed.\nNot available for milestone type of work packages.",
      "readOnly": true
    },
    "estimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed excluding its descendants"
    },
    "derivedEstimatedTime": {
      "type": "string",
      "format": "duration",
      "description": "Time a work package likely needs to be completed including its descendants",
      "readOnly": true
    },
    "ignoreNonWorkingDays": {
      "type": "boolean",
      "description": "**(NOT IMPLEMENTED)** When scheduling, whether or not to ignore the non working days being defined.\nA work package with the flag set to true will be allowed to be scheduled to a non working day.",
      "readOnly": true
    },
    "spentTime": {
      "type": "string",
      "format": "duration",
      "description": "The time booked for this work package by users working on it\n\n# Conditions\n\n**Permission** view time entries",
      "readOnly": true
    },
    "percentageDone": {
      "type": "integer",
      "description": "Amount of total completion for a work package",
      "maximum": 100
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the work package",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "ancestors",
        "attachments",
        "author",
        "children",
        "priority",
        "project",
        "status",
        "type"
      ],
      "properties": {
        "addAttachment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Attach a file to the WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "addComment": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post comment to WP\n\n# Conditions\n\n**Permission**: add work package notes",
              "readOnly": true
            }
          ]
        },
        "addRelation": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Adds a relation to this work package.\n\n# Conditions\n\n**Permission**: manage wp relations",
              "readOnly": true
            }
          ]
        },
        "addWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add any user to WP watchers\n\n# Conditions\n\n**Permission**: add watcher",
              "readOnly": true
            }
          ]
        },
        "customActions": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A predefined action that can be applied to the work package.\n\n**Resource**: CustomAction",
                "readOnly": true
              }
            ]
          }
        },
        "previewMarkup": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Post markup (in markdown) here to receive an HTML-rendered response",
              "readOnly": true
            }
          ]
        },
        "removeWatcher": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove any user from WP watchers\n\n# Conditions\n\n**Permission**: delete watcher",
              "readOnly": true
            }
          ]
        },
        "unwatch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Remove current user from WP watchers\n\n# Conditions\n\nlogged in; watching",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Form endpoint that aids in preparing and performing edits on a WP\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Directly perform edits on a work package\n\n# Conditions\n\n**Permission**: edit work package",
              "readOnly": true
            }
          ]
        },
        "watch": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add current user to WP watchers\n\n# Conditions\n\nlogged in; not watching",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This work package\n\n**Resource**: WorkPackage",
              "readOnly": true
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema of this work package\n\n**Resource**: Schema",
              "readOnly": true
            }
          ]
        },
        "ancestors": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible ancestor work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "attachments": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The files attached to this work package\n\n**Resource**: Collection"
            }
          ]
        },
        "author": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that created the work package\n\n**Resource**: User",
              "readOnly": true
            }
          ]
        },
        "assignee": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is intended to work on the work package\n\n**Resource**: User"
            }
          ]
        },
        "availableWatchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that can be added to the work package as watchers.\n\n**Resource**: User\n\n# Conditions\n\n**Permission** add work package watchers",
              "readOnly": true
            }
          ]
        },
        "budget": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The budget this work package is associated to\n\n**Resource**: Budget\n\n# Conditions\n\n**Permission** view cost objects"
            }
          ]
        },
        "category": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The category of the work package\n\n**Resource**: Category"
            }
          ]
        },
        "children": {
          "type": "array",
          "readOnly": true,
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A visible child work package of the current work package.\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission** view work packages",
                "readOnly": true
              }
            ]
          }
        },
        "addFileLink": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Add a file link to the work package\n\n# Conditions\n\n**Permission**: manage file links"
            }
          ]
        },
        "fileLinks": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Gets the file link collection of this work package\n\n# Conditions\n\n**Permission**: view file links"
            }
          ]
        },
        "parent": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Parent work package\n\n**Resource**: WorkPackage"
            }
          ]
        },
        "priority": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The priority of the work package\n\n**Resource**: Priority"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project to which the work package belongs\n\n**Resource**: Project"
            }
          ]
        },
        "responsible": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The person that is responsible for the overall outcome\n\n**Resource**: User"
            }
          ]
        },
        "relations": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Relations this work package is involved in\n\n**Resource**: Relation\n\n# Conditions\n\n**Permission** view work packages",
              "readOnly": true
            }
          ]
        },
        "revisions": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Revisions that are referencing the work package\n\n**Resource**: Revision\n\n# Conditions\n\n**Permission** view changesets",
              "readOnly": true
            }
          ]
        },
        "status": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The current status of the work package\n\n**Resource**: Status"
            }
          ]
        },
        "timeEntries": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All time entries logged on the work package. Please note that this is a link to an HTML resource for now and as such, the link is subject to change.\n\n**Resource**: N/A\n\n# Conditions\n\n**Permission** view time entries",
              "readOnly": true
            }
          ]
        },
        "type": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The type of the work package\n\n**Resource**: Type"
            }
          ]
        },
        "version": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The version associated to the work package\n\n**Resource**: Version"
            }
          ]
        },
        "watchers": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "All users that are currently watching this work package\n\n**Resource**: Collection\n\n# Conditions\n\n**Permission** view work package watchers",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "WorkPackage",
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/1528",
        "title": "Develop API"
      },
      "schema": {
        "href": "/api/v3/work_packages/schemas/11-2"
      },
      "update": {
        "href": "/api/v3/work_packages/1528",
        "method": "patch",
        "title": "Update Develop API"
      },
      "delete": {
        "href": "/work_packages/bulk?ids=1528",
        "method": "delete",
        "title": "Delete Develop API"
      },
      "logTime": {
        "href": "/work_packages/1528/time_entries/new",
        "type": "text/html",
        "title": "Log time on Develop API"
      },
      "move": {
        "href": "/work_packages/1528/move/new",
        "type": "text/html",
        "title": "Move Develop API"
      },
      "attachments": {
        "href": "/api/v3/work_packages/1528/attachments"
      },
      "addAttachment": {
        "href": "/api/v3/work_packages/1528/attachments",
        "method": "post"
      },
      "author": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin - admin"
      },
      "customActions": [
        {
          "href": "/api/v3/work_packages/1528/custom_actions/153/execute",
          "method": "post",
          "title": "Reset"
        },
        {
          "href": "/api/v3/work_packages/1528/custom_actions/94/execute",
          "method": "post",
          "title": "Forward to accounting"
        }
      ],
      "responsible": {
        "href": "/api/v3/users/23",
        "title": "Laron Leuschke - Alaina5788"
      },
      "relations": {
        "href": "/api/v3/work_packages/1528/relations",
        "title": "Show relations"
      },
      "revisions": {
        "href": "/api/v3/work_packages/1528/revisions"
      },
      "assignee": {
        "href": "/api/v3/users/11",
        "title": "Emmie Okuneva - Adele5450"
      },
      "priority": {
        "href": "/api/v3/priorities/2",
        "title": "Normal"
      },
      "project": {
        "href": "/api/v3/projects/1",
        "title": "A Test Project"
      },
      "status": {
        "href": "/api/v3/statuses/1",
        "title": "New"
      },
      "type": {
        "href": "/api/v3/types/1",
        "title": "A Type"
      },
      "version": {
        "href": "/api/v3/versions/1",
        "title": "Version 1"
      },
      "availableWatchers": {
        "href": "/api/v3/work_packages/1528/available_watchers"
      },
      "watch": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/1"
          }
        }
      },
      "addWatcher": {
        "href": "/api/v3/work_packages/1528/watchers",
        "method": "post",
        "payload": {
          "user": {
            "href": "/api/v3/users/{user_id}"
          }
        },
        "templated": true
      },
      "removeWatcher": {
        "href": "/api/v3/work_packages/1528/watchers/{user_id}",
        "method": "delete",
        "templated": true
      },
      "addRelation": {
        "href": "/api/v3/relations",
        "method": "post",
        "title": "Add relation"
      },
      "changeParent": {
        "href": "/api/v3/work_packages/694",
        "method": "patch",
        "title": "Change parent of Bug in OpenProject"
      },
      "addComment": {
        "href": "/api/v3/work_packages/1528/activities",
        "method": "post",
        "title": "Add comment"
      },
      "parent": {
        "href": "/api/v3/work_packages/1298",
        "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
      },
      "category": {
        "href": "/api/v3/categories/1298",
        "title": "eligend isi"
      },
      "children": [
        {
          "href": "/api/v3/work_packages/1529",
          "title": "Write API documentation"
        }
      ],
      "ancestors": [
        {
          "href": "/api/v3/work_packages/1290",
          "title": "Root node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1291",
          "title": "Intermediate node of hierarchy"
        },
        {
          "href": "/api/v3/work_packages/1298",
          "title": "nisi eligendi officiis eos delectus quis voluptas dolores"
        }
      ],
      "timeEntries": {
        "href": "/work_packages/1528/time_entries",
        "type": "text/html",
        "title": "Time entries"
      },
      "watchers": {
        "href": "/api/v3/work_packages/1528/watchers"
      },
      "customField3": {
        "href": "api/v3/users/14"
      }
    },
    "id": 1528,
    "subject": "Develop API",
    "description": {
      "format": "markdown",
      "raw": "Develop super cool OpenProject API.",
      "html": "<p>Develop super cool OpenProject API.</p>"
    },
    "scheduleManually": false,
    "readonly": false,
    "startDate": null,
    "dueDate": null,
    "derivedStartDate": null,
    "derivedDueDate": null,
    "estimatedTime": "PT2H",
    "derivedEstimatedTime": "PT10H",
    "percentageDone": 0,
    "customField1": "Foo",
    "customField2": 42,
    "createdAt": "2014-08-29T12:40:53Z",
    "updatedAt": "2014-08-29T12:44:41Z"
  }
}

400

403

Returned if the client does not have sufficient permissions.

Required permission: edit work package, assign version, manage subtasks or move work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to edit the content of the work package."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

406

409

Returned if the resource was changed since the client requested it. This is determined using the lockVersion property.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
  "message": "Your changes could not be saved, because the work package was changed since you've seen it the last time."
}
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."
    }
  }
}

415

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)
  • a constraint for a property was violated (PropertyConstraintViolation)
  • the client provides a link to an invalid resource (ResourceTypeMismatch)
{
  "_embedded": {
    "details": {
      "attribute": "Subject"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The subject might not 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 work package

Deletes the work package, as well as:

  • all associated time entries
  • its hierarchy of child work packages

id
integer

required path

Work package id

Example:
1

204

Returned if the work package was deleted successfully.

Note that the response body is empty as of now. In future versions of the API a body might be returned along with an appropriate HTTP status.

403

Returned if the client does not have sufficient permissions.

Required permission: delete work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this work package."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

406

415

List work package activities

id
integer

required path

Work package id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/activity/1"
          },
          "user": {
            "href": "/api/v3/users/1"
          },
          "workPackage": {
            "href": "/api/v3/work_packages/1"
          }
        },
        "_type": "Activity",
        "comment": {
          "format": "markdown",
          "html": "<p>Lorem ipsum dolor sit amet.</p>",
          "raw": "Lorem ipsum dolor sit amet."
        },
        "createdAt": "2014-05-21T08:51:20Z",
        "updatedAt": "2014-05-21T09:14:02Z",
        "details": [

        ],
        "id": 1,
        "version": 1
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/activity/2"
          },
          "user": {
            "href": "/api/v3/users/1"
          },
          "workPackage": {
            "href": "/api/v3/work_packages/1"
          }
        },
        "_type": "Activity",
        "comment": {
          "format": "markdown",
          "html": "<p>Lorem ipsum dolor sit amet.</p>",
          "raw": "Lorem ipsum dolor sit amet."
        },
        "createdAt": "2014-05-21T09:51:22Z",
        "updatedAt": "2014-05-21T10:14:02Z",
        "details": [

        ],
        "id": 2,
        "version": 2
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/work_packages/1/revisions"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Work_Package_activitiesModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/1/revisions"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "Activity",
          "_links": {
            "self": {
              "href": "/api/v3/activity/1"
            },
            "workPackage": {
              "href": "/api/v3/work_packages/1"
            },
            "user": {
              "href": "/api/v3/users/1"
            }
          },
          "id": 1,
          "details": [

          ],
          "comment": {
            "format": "markdown",
            "raw": "Lorem ipsum dolor sit amet.",
            "html": "<p>Lorem ipsum dolor sit amet.</p>"
          },
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T09:14:02Z",
          "version": 1
        },
        {
          "_type": "Activity",
          "_links": {
            "self": {
              "href": "/api/v3/activity/2"
            },
            "workPackage": {
              "href": "/api/v3/work_packages/1"
            },
            "user": {
              "href": "/api/v3/users/1"
            }
          },
          "id": 2,
          "details": [

          ],
          "comment": {
            "format": "markdown",
            "raw": "Lorem ipsum dolor sit amet.",
            "html": "<p>Lorem ipsum dolor sit amet.</p>"
          },
          "createdAt": "2014-05-21T09:51:22Z",
          "updatedAt": "2014-05-21T10:14:02Z",
          "version": 2
        }
      ]
    }
  }
}

404

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

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

Comment work package

Creates an activity for the selected work package and, on success, returns the updated activity.

id
integer

required path

Work package id

Example:
1

notify
boolean

optional query

Indicates whether change notifications (e.g. via E-Mail) should be sent. Note that this controls notifications for all users interested in changes to the work package (e.g. watchers, author and assignee), not just the current user.

Default:
true

Example:
false

{
  "comment": {
    "raw": "I think this is awesome!"
  }
}

{
  "comment": {
    "properties": {
      "raw": {
        "type": "string"
      }
    },
    "type": "object"
  }
}

201

Created

400

403

Returned if the client does not have sufficient permissions.

Required permission: create journals

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to create a comment here."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

Available projects for work package

Gets a list of projects that are available as projects to which the work package can be moved.

id
integer

required path

work package id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "categories": {
            "href": "/api/v3/projects/6/categories"
          },
          "createWorkPackage": {
            "href": "/api/v3/projects/6/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/projects/6/work_packages",
            "method": "post"
          },
          "editWorkPackage": {
            "href": "/api/v3//work_packages/{id}/form",
            "method": "post",
            "templated": true
          },
          "self": {
            "href": "/api/v3/projects/6",
            "title": "A project"
          },
          "versions": {
            "href": "/api/v3/projects/6/versions"
          }
        },
        "_type": "Project",
        "createdAt": "2015-07-06T13:28:14+00:00",
        "description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
        "id": 6,
        "identifier": "a_project",
        "name": "A project",
        "type": "Customer Project",
        "updatedAt": "2015-10-01T09:55:02+00:00"
      },
      {
        "_links": {
          "categories": {
            "href": "/api/v3/projects/14/categories"
          },
          "createWorkPackage": {
            "href": "/api/v3/projects/14/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/projects/14/work_packages",
            "method": "post"
          },
          "self": {
            "href": "/api/v3/projects/14",
            "title": "Another project"
          },
          "versions": {
            "href": "/api/v3/projects/14/versions"
          }
        },
        "_type": "Project",
        "createdAt": "2016-02-29T12:50:20+00:00",
        "description": "",
        "id": 14,
        "identifier": "another_project",
        "name": "Another project",
        "type": null,
        "updatedAt": "2016-02-29T12:50:20+00:00"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/work_packages/5/available_projects"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Available_projects_for_work_packageModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/5/available_projects"
      }
    },
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_embedded": {
      "elements": [
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/6",
              "title": "A project"
            },
            "editWorkPackage": {
              "href": "/api/v3/work_packages/{id}/form",
              "templated": true,
              "method": "post"
            },
            "createWorkPackage": {
              "href": "/api/v3/projects/6/work_packages/form",
              "method": "post"
            },
            "createWorkPackageImmediate": {
              "href": "/api/v3/projects/6/work_packages",
              "method": "post"
            },
            "categories": {
              "href": "/api/v3/projects/6/categories"
            },
            "versions": {
              "href": "/api/v3/projects/6/versions"
            }
          },
          "id": 6,
          "identifier": "a_project",
          "name": "A project",
          "description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
          "createdAt": "2015-07-06T13:28:14+00:00",
          "updatedAt": "2015-10-01T09:55:02+00:00",
          "type": "Customer Project"
        },
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/14",
              "title": "Another project"
            },
            "createWorkPackage": {
              "href": "/api/v3/projects/14/work_packages/form",
              "method": "post"
            },
            "createWorkPackageImmediate": {
              "href": "/api/v3/projects/14/work_packages",
              "method": "post"
            },
            "categories": {
              "href": "/api/v3/projects/14/categories"
            },
            "versions": {
              "href": "/api/v3/projects/14/versions"
            }
          },
          "id": 14,
          "identifier": "another_project",
          "name": "Another project",
          "description": "",
          "createdAt": "2016-02-29T12:50:20+00:00",
          "updatedAt": "2016-02-29T12:50:20+00:00",
          "type": null
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: edit work package

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

Available relation candidates

id
integer

required path

Project id

Example:
1

pageSize
integer

optional query

Maximum number of candidates to list (default 10)

Example:
25

filters
string

optional query

JSON specifying filter conditions. Accepts the same filters as the work packages endpoint.

Example:
[{ "status_id": { "operator": "o", "values": null } }]

query
string

optional query

Shortcut for filtering by ID or subject

Example:
"rollout"

type
string

optional query

Type of relation to find candidates for (default “relates”)

Example:
"follows"

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same sort criteria as the work packages endpoint.

Default:
[["id", "asc"]]

Example:
[["status", "asc"]]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/work_packages/1"
          }
        },
        "_type": "WorkPackage",
        "id": 1,
        "subject": "Skipped other properties for brevity"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/work_packages/2"
          }
        },
        "_type": "WorkPackage",
        "id": 2,
        "subject": "Skipped other properties for brevity"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects/14/work_packages"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Available_relation_candidatesModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/projects/14/work_packages"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "WorkPackage",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/1"
            }
          },
          "id": 1,
          "subject": "Skipped other properties for brevity"
        },
        {
          "_type": "WorkPackage",
          "_links": {
            "self": {
              "href": "/api/v3/work_packages/2"
            }
          },
          "id": 2,
          "subject": "Skipped other properties for brevity"
        }
      ]
    }
  }
}

Available watchers

Gets a list of users that are able to be watchers of the specified work package.

id
integer

required path

work package id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/1",
            "method": "DELETE",
            "title": "Delete j.sheppard"
          },
          "lock": {
            "href": "/api/v3/users/1/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard"
          },
          "self": {
            "href": "/api/v3/users/1",
            "title": "John Sheppard - j.sheppard"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.com",
        "firstName": "John",
        "id": 1,
        "lastName": "Sheppard",
        "login": "j.sheppard",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      },
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/2",
            "method": "DELETE",
            "title": "Delete j.sheppard2"
          },
          "lock": {
            "href": "/api/v3/users/2/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard2"
          },
          "self": {
            "href": "/api/v3/users/2",
            "title": "Jim Sheppard - j.sheppard2"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "email": "shep@mail.net",
        "firstName": "Jim",
        "id": 2,
        "lastName": "Sheppard",
        "login": "j.sheppard2",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/work_packages/1/available_watchers"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Available_WatchersModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/1/available_watchers"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/1",
              "title": "John Sheppard - j.sheppard"
            },
            "lock": {
              "href": "/api/v3/users/1/lock",
              "title": "Set lock on j.sheppard",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/1",
              "title": "Delete j.sheppard",
              "method": "DELETE"
            }
          },
          "id": 1,
          "login": "j.sheppard",
          "firstName": "John",
          "lastName": "Sheppard",
          "email": "shep@mail.com",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        },
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/2",
              "title": "Jim Sheppard - j.sheppard2"
            },
            "lock": {
              "href": "/api/v3/users/2/lock",
              "title": "Set lock on j.sheppard2",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/2",
              "title": "Delete j.sheppard2",
              "method": "DELETE"
            }
          },
          "id": 2,
          "login": "j.sheppard2",
          "firstName": "Jim",
          "lastName": "Sheppard",
          "email": "shep@mail.net",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: add work package watchers

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

Work package edit form

When calling this endpoint, the client provides a single object containing the properties and links to be edited, in the body.

Note that it is only allowed to provide properties or links supporting the write operation.

When setting start date, finish date, and duration together, their correctness will be checked and a 422 error will be returned if one value does not match with the two others. You can make the server compute a value: set only two values in the request and the third one will be computed and returned in the response. For instance, when sending { "startDate": "2022-08-23", duration: "P2D" }, the response will include { "dueDate": "2022-08-24" }.

id
integer

required path

ID of the work package being modified

Example:
1

200

OK

403

Returned if the client does not have sufficient permissions.

Required permission: edit work package, assign version, manage subtasks or move work package

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to edit the specified work package."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

406

415

List relations

Lists all relations this work package is involved in.

id
integer

required path

Work package id

Example:
1

302

Found

"You are being redirected to /api/v3/relations?involved={work_package_id}"

{
  "type": "string"
}

Create relation

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a Relation can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

id
integer

required path

Work package id

Example:
1

201

Created

400

403

Returned if the client does not have sufficient permissions.

Required permission: manage work package relations

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to create a relation."
}
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."
    }
  }
}

409

Returned if there already exists a relation between the given work packages of any type or if the relation is not allowed.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
  "message": "Couldn't update the resource because of conflicting modifications."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

415

422

Returned if:

  • the client tries to write a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

  • the client provides a link to an invalid resource (ResourceTypeMismatch)

{
  "_embedded": {
    "details": {
      "attribute": "delay"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Delay must be a number greater than or equal to 0"
}
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."
    }
  }
}

Revisions

Gets a list of revisions that are linked to this work package, e.g., because it is referenced in the commit message of the revision. Only linked revisions from repositories are shown if the user has the view changesets permission in the defining project.

id
integer

required path

Work package id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "author": {
            "href": "/api/v3/users/1",
            "title": "John Sheppard - j.sheppard"
          },
          "project": {
            "href": "/api/v3/projects/1",
            "title": "A Test Project"
          },
          "self": {
            "href": "/api/v3/revisions/13"
          },
          "showRevision": {
            "href": "/projects/identifier/repository/revision/11f4b07"
          }
        },
        "_type": "Revision",
        "authorName": "John Sheppard",
        "createdAt": "2015-07-21T13:36:59Z",
        "formattedIdentifier": "11f4b07",
        "id": 13,
        "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
        "message": {
          "format": "plain",
          "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>",
          "raw": "This revision provides new features\n\nAn elaborate description"
        }
      },
      {
        "_links": {
          "author": {
            "href": "/api/v3/users/2",
            "title": "Jim Sheppard - j.sheppard"
          },
          "project": {
            "href": "/api/v3/projects/1",
            "title": "A Test Project"
          },
          "self": {
            "href": "/api/v3/revisions/14"
          },
          "showRevision": {
            "href": "/projects/identifier/repository/revision/029ed72a"
          }
        },
        "_type": "Revision",
        "authorName": "j1msheppard",
        "createdAt": "2015-06-30T08:47:00Z",
        "formattedIdentifier": "029ed72a",
        "id": 13,
        "identifier": "029ed72a3b7b7c4ab332b1f6eaa6576e7c946059",
        "message": {
          "format": "plain",
          "html": "<p>This revision fixes some stuff<br/><br/>More information here</p>",
          "raw": "This revision fixes some stuff\n\nMore information here"
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/work_packages/42/revisions"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
RevisionsModel 
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/42/revisions"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "Revision",
          "_links": {
            "self": {
              "href": "/api/v3/revisions/13"
            },
            "project": {
              "href": "/api/v3/projects/1",
              "title": "A Test Project"
            },
            "author": {
              "href": "/api/v3/users/1",
              "title": "John Sheppard - j.sheppard"
            },
            "showRevision": {
              "href": "/projects/identifier/repository/revision/11f4b07"
            }
          },
          "id": 13,
          "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6",
          "formattedIdentifier": "11f4b07",
          "authorName": "John Sheppard",
          "message": {
            "format": "plain",
            "raw": "This revision provides new features\n\nAn elaborate description",
            "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>"
          },
          "createdAt": "2015-07-21T13:36:59Z"
        },
        {
          "_type": "Revision",
          "_links": {
            "self": {
              "href": "/api/v3/revisions/14"
            },
            "project": {
              "href": "/api/v3/projects/1",
              "title": "A Test Project"
            },
            "author": {
              "href": "/api/v3/users/2",
              "title": "Jim Sheppard - j.sheppard"
            },
            "showRevision": {
              "href": "/projects/identifier/repository/revision/029ed72a"
            }
          },
          "id": 13,
          "identifier": "029ed72a3b7b7c4ab332b1f6eaa6576e7c946059",
          "formattedIdentifier": "029ed72a",
          "authorName": "j1msheppard",
          "message": {
            "format": "plain",
            "raw": "This revision fixes some stuff\n\nMore information here",
            "html": "<p>This revision fixes some stuff<br/><br/>More information here</p>"
          },
          "createdAt": "2015-06-30T08:47:00Z"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages for the project the work package is contained in.

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see linked revisions for this work package."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work project does not exist."
}
ErrorResponse 
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List watchers

id
integer

required path

Work package id

Example:
1

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/1",
            "method": "DELETE",
            "title": "Delete j.sheppard"
          },
          "lock": {
            "href": "/api/v3/users/1/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard"
          },
          "self": {
            "href": "/api/v3/users/1",
            "title": "John Sheppard - j.sheppard"
          },
          "showUser": {
            "href": "/users/1",
            "type": "text/html"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "firstName": "John",
        "id": 1,
        "lastName": "Sheppard",
        "login": "j.sheppard",
        "mail": "shep@mail.com",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      },
      {
        "_links": {
          "delete": {
            "href": "/api/v3/users/2",
            "method": "DELETE",
            "title": "Delete j.sheppard2"
          },
          "lock": {
            "href": "/api/v3/users/2/lock",
            "method": "POST",
            "title": "Set lock on j.sheppard2"
          },
          "self": {
            "href": "/api/v3/users/2",
            "title": "Jim Sheppard - j.sheppard2"
          }
        },
        "_type": "User",
        "avatar": "https://example.org/users/1/avatar",
        "createdAt": "2014-05-21T08:51:20Z",
        "firstName": "Jim",
        "id": 2,
        "lastName": "Sheppard",
        "login": "j.sheppard2",
        "mail": "shep@mail.net",
        "status": "active",
        "updatedAt": "2014-05-21T08:51:20Z"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/work_packages/14/watchers"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
WatchersModel 
{
  "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 watcher list\n\n**Resource**: WatchersModel",
                  "readOnly": true
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "properties": {
            "elements": {
              "type": "array",
              "readOnly": true,
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/UserModel"
                  },
                  {
                    "description": "Collection of Users"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/work_packages/14/watchers"
      }
    },
    "total": 2,
    "count": 2,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/1",
              "title": "John Sheppard - j.sheppard"
            },
            "showUser": {
              "href": "/users/1",
              "type": "text/html"
            },
            "lock": {
              "href": "/api/v3/users/1/lock",
              "title": "Set lock on j.sheppard",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/1",
              "title": "Delete j.sheppard",
              "method": "DELETE"
            }
          },
          "id": 1,
          "login": "j.sheppard",
          "firstName": "John",
          "lastName": "Sheppard",
          "mail": "shep@mail.com",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        },
        {
          "_type": "User",
          "_links": {
            "self": {
              "href": "/api/v3/users/2",
              "title": "Jim Sheppard - j.sheppard2"
            },
            "lock": {
              "href": "/api/v3/users/2/lock",
              "title": "Set lock on j.sheppard2",
              "method": "POST"
            },
            "delete": {
              "href": "/api/v3/users/2",
              "title": "Delete j.sheppard2",
              "method": "DELETE"
            }
          },
          "id": 2,
          "login": "j.sheppard2",
          "firstName": "Jim",
          "lastName": "Sheppard",
          "mail": "shep@mail.net",
          "avatar": "https://example.org/users/1/avatar",
          "status": "active",
          "createdAt": "2014-05-21T08:51:20Z",
          "updatedAt": "2014-05-21T08:51:20Z"
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work package watchers

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the watchers of this work package."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

Note that you will effectively not be able to see the watchers of a work package without being able to see the work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

Add watcher

Adds a watcher to the specified work package.

The request is expected to contain a single JSON object, that contains a link object under the user key.

The response will be user added as watcher. In case the user was already watching the work package an HTTP 200 is returned, an HTTP 201 if the user was added as a new watcher.

id
integer

required path

Work package id

Example:
1

{
  "user": {
    "href": "/api/v3/users/1"
  }
}

{
  "user": {
    "properties": {
      "href": {
        "type": "string"
      }
    },
    "type": "object"
  }
}

200

OK

201

Created

400

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

For example:

  • The request did not contain a single JSON object

  • The JSON object did not contain the key user

  • The value of users was not a link object

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

  • view work package (for self)

  • add work package watchers (for other users)

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to add watchers to this work package."
}
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 work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

406

415

422

Returned if:

  • the client tries to specify a link to a resource that is not a user (ResourceTypeMismatch)

  • the user specified is not allowed to watch that work package (PropertyConstraintViolation)

  • the user specified does not exist (PropertyConstraintViolation)

Remove watcher

Removes the specified user from the list of watchers for the given work package.

If the request succeeds, the specified user is not watching the work package anymore.

Note: This might also be the case, if the specified user did not watch the work package prior to the request.

id
integer

required path

Work package id

Example:
1

user_id
integer

required path

User id

Example:
1

204

No Content

403

Returned if the client does not have sufficient permissions.

Required permission: delete work package watchers

Note that you will only receive this error, if you are at least allowed to see the corresponding work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to remove watchers from this work package."
}
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 in one of the following cases:

Either the work package does not exist or the client does not have sufficient permissions to see it.

Required permission: view work package

Or the specified user does not exist at all.

Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified work package 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."
    }
  }
}

406

415