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 | Corresponds to work. Time a work package likely needs to be completed. | Duration | READ / WRITE | ||
derivedEstimatedTime | Corresponds to total work. Time a work package likely needs to be completed including itself and its descendants. | Duration | READ | ||
remainingTime | Corresponds to remaining work. Remaining time a work package likely needs to be completed. | Duration | READ / WRITE | ||
derivedRemainingTime | Corresponds to total remaining work. Remaining time a work package likely needs to be completed including itself and 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 | Corresponds to % complete. Amount of total completion for a work package. | Integer | 0 <= x <= 100; can be null | READ | |
derivedPercentageDone | Corresponds to total % complete. Amount of total completion for a work package and its descendants. | Integer | 0 <= x <= 100; can be null | READ | |
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. -
derivedEstimatedTime
is the sum of estimated times from its children and the work package’s own estimated time. -
derivedRemainingTime
is the sum of remaining times from its children and the work package’s own remaining time -
derivedPercentageDone
is computed by the work package’s derivedEstimatedTime and derivedRemainingTime.
startDate
can also not be earlier than a finish date of any predecessor.
While attachments are returned as a link whose 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
Project 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:20.396Z",
"email": "shep@mail.com",
"firstName": "John",
"id": 1,
"lastName": "Sheppard",
"login": "j.sheppard",
"status": "active",
"updatedAt": "2014-05-21T08:51:20.396Z"
},
{
"_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:20.396Z",
"email": "shep@mail.net",
"firstName": "Jim",
"id": 2,
"lastName": "Sheppard",
"login": "j.sheppard2",
"status": "active",
"updatedAt": "2014-05-21T08:51:20.396Z"
}
]
},
"_links": {
"self": {
"href": "/api/v3/projects/42/available_assignees"
}
},
"_type": "Collection",
"count": 2,
"total": 2
}
Available_AssigneesModel
{
"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 available assignees collection\n\n**Resource**: AvailableAssigneesCollection",
"readOnly": true
}
]
}
}
},
"_embedded": {
"type": "object",
"properties": {
"elements": {
"type": "array",
"readOnly": true,
"items": {
"allOf": [
{
"$ref": "#/components/schemas/UserModel"
},
{
"description": "Collection of Users"
}
]
}
}
}
}
}
}
]
}
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 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."
}
}
}
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
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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
{
"_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:53.373Z",
"updatedAt": "2014-08-29T12:44:41.981Z"
}
{
"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",
"minimum": 0,
"maximum": 100
},
"derivedPercentageDone": {
"type": "integer",
"description": "Amount of total completion for a work package derived from itself and its descendant work packages",
"readOnly": true,
"minimum": 0,
"maximum": 100
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.",
"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": {
"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
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this work package\n\n# Conditions\n\n**Permission**: delete_work_packages",
"readOnly": true
}
]
},
"logTime": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Create time entries on the work package\n\n# Conditions\n\n**Permission**: log_time or log_own_time",
"readOnly": true
}
]
},
"move": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for moving this work package\n\n# Conditions\n\n**Permission**: move_work_packages",
"readOnly": true
}
]
},
"copy": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for copying this work package\n\n# Conditions\n\n**Permission**: add_work_packages",
"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 work package\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\n\n# Conditions\n\n- **Setting**: deactivate_work_package_attachments set to false in related project"
}
]
},
"addAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Permission**: edit work package",
"readOnly": true
}
]
},
"prepareAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Setting**: direct uploads enabled",
"readOnly": true
}
]
},
"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
}
]
}
}
}
}
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",
"minimum": 0,
"maximum": 100
},
"derivedPercentageDone": {
"type": "integer",
"description": "Amount of total completion for a work package derived from itself and its descendant work packages",
"readOnly": true,
"minimum": 0,
"maximum": 100
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.",
"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": {
"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
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this work package\n\n# Conditions\n\n**Permission**: delete_work_packages",
"readOnly": true
}
]
},
"logTime": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Create time entries on the work package\n\n# Conditions\n\n**Permission**: log_time or log_own_time",
"readOnly": true
}
]
},
"move": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for moving this work package\n\n# Conditions\n\n**Permission**: move_work_packages",
"readOnly": true
}
]
},
"copy": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for copying this work package\n\n# Conditions\n\n**Permission**: add_work_packages",
"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 work package\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\n\n# Conditions\n\n- **Setting**: deactivate_work_package_attachments set to false in related project"
}
]
},
"addAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Permission**: edit work package",
"readOnly": true
}
]
},
"prepareAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Setting**: direct uploads enabled",
"readOnly": true
}
]
},
"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:53.373Z",
"updatedAt": "2014-08-29T12:44:41.981Z"
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: add 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
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
-
the 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, such as ISO8601 dates, ISO8601 durations and the following relative date keywords: “oneDayAgo@HH:MM+HH:MM”, “lastWorkingDay@HH:MM+HH:MM”, “oneWeekAgo@HH:MM+HH:MM”, “oneMonthAgo@HH:MM+HH:MM”. The first “HH:MM” part represents the zero paded hours and minutes. The last “+HH:MM” part represents the timezone offset from UTC associated with the time, the offset can be positive or negative e.g.“oneDayAgo@01:00+01:00”, “oneDayAgo@01:00-01:00”.
Usually, the first timestamp is the baseline date, the last timestamp is the current date. Values older than 1 day are accepted only with valid Enterprise Token available.
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
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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
{
"_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:53.373Z",
"updatedAt": "2014-08-29T12:44:41.981Z"
}
{
"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",
"minimum": 0,
"maximum": 100
},
"derivedPercentageDone": {
"type": "integer",
"description": "Amount of total completion for a work package derived from itself and its descendant work packages",
"readOnly": true,
"minimum": 0,
"maximum": 100
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.",
"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": {
"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
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this work package\n\n# Conditions\n\n**Permission**: delete_work_packages",
"readOnly": true
}
]
},
"logTime": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Create time entries on the work package\n\n# Conditions\n\n**Permission**: log_time or log_own_time",
"readOnly": true
}
]
},
"move": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for moving this work package\n\n# Conditions\n\n**Permission**: move_work_packages",
"readOnly": true
}
]
},
"copy": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for copying this work package\n\n# Conditions\n\n**Permission**: add_work_packages",
"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 work package\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\n\n# Conditions\n\n- **Setting**: deactivate_work_package_attachments set to false in related project"
}
]
},
"addAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Permission**: edit work package",
"readOnly": true
}
]
},
"prepareAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Setting**: direct uploads enabled",
"readOnly": true
}
]
},
"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
}
]
}
}
}
}
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",
"minimum": 0,
"maximum": 100
},
"derivedPercentageDone": {
"type": "integer",
"description": "Amount of total completion for a work package derived from itself and its descendant work packages",
"readOnly": true,
"minimum": 0,
"maximum": 100
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.",
"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": {
"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
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this work package\n\n# Conditions\n\n**Permission**: delete_work_packages",
"readOnly": true
}
]
},
"logTime": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Create time entries on the work package\n\n# Conditions\n\n**Permission**: log_time or log_own_time",
"readOnly": true
}
]
},
"move": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for moving this work package\n\n# Conditions\n\n**Permission**: move_work_packages",
"readOnly": true
}
]
},
"copy": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for copying this work package\n\n# Conditions\n\n**Permission**: add_work_packages",
"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 work package\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\n\n# Conditions\n\n- **Setting**: deactivate_work_package_attachments set to false in related project"
}
]
},
"addAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Permission**: edit work package",
"readOnly": true
}
]
},
"prepareAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Setting**: direct uploads enabled",
"readOnly": true
}
]
},
"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:53.373Z",
"updatedAt": "2014-08-29T12:44:41.981Z"
}
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: add 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
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
-
the 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
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
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: 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, such as ISO8601 dates, ISO8601 durations and the following relative date keywords: “oneDayAgo@HH:MM+HH:MM”, “lastWorkingDay@HH:MM+HH:MM”, “oneWeekAgo@HH:MM+HH:MM”, “oneMonthAgo@HH:MM+HH:MM”. The first “HH:MM” part represents the zero paded hours and minutes. The last “+HH:MM” part represents the timezone offset from UTC associated with the time, the offset can be positive or negative e.g.“oneDayAgo@01:00+01:00”, “oneDayAgo@01:00-01:00”.
Usually, the first timestamp is the baseline date, the last timestamp is the current date. Values older than 1 day are accepted only with valid Enterprise Token available.
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",
"minimum": 0,
"maximum": 100
},
"derivedPercentageDone": {
"type": "integer",
"description": "Amount of total completion for a work package derived from itself and its descendant work packages",
"readOnly": true,
"minimum": 0,
"maximum": 100
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.",
"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": {
"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
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this work package\n\n# Conditions\n\n**Permission**: delete_work_packages",
"readOnly": true
}
]
},
"logTime": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Create time entries on the work package\n\n# Conditions\n\n**Permission**: log_time or log_own_time",
"readOnly": true
}
]
},
"move": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for moving this work package\n\n# Conditions\n\n**Permission**: move_work_packages",
"readOnly": true
}
]
},
"copy": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for copying this work package\n\n# Conditions\n\n**Permission**: add_work_packages",
"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 work package\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\n\n# Conditions\n\n- **Setting**: deactivate_work_package_attachments set to false in related project"
}
]
},
"addAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Permission**: edit work package",
"readOnly": true
}
]
},
"prepareAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Setting**: direct uploads enabled",
"readOnly": true
}
]
},
"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:53.373Z",
"updatedAt": "2014-08-29T12:44:41.981Z"
}
}
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."
}
}
}
Update a 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:42
notify
boolean
optional query
Indicates whether change notifications 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
{
"_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:53.373Z",
"updatedAt": "2014-08-29T12:44:41.981Z"
}
{
"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",
"minimum": 0,
"maximum": 100
},
"derivedPercentageDone": {
"type": "integer",
"description": "Amount of total completion for a work package derived from itself and its descendant work packages",
"readOnly": true,
"minimum": 0,
"maximum": 100
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Time of creation. Can be writable by admins with the `apiv3_write_readonly_attributes` setting enabled.",
"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": {
"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
}
]
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Delete this work package\n\n# Conditions\n\n**Permission**: delete_work_packages",
"readOnly": true
}
]
},
"logTime": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Create time entries on the work package\n\n# Conditions\n\n**Permission**: log_time or log_own_time",
"readOnly": true
}
]
},
"move": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for moving this work package\n\n# Conditions\n\n**Permission**: move_work_packages",
"readOnly": true
}
]
},
"copy": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Link to page for copying this work package\n\n# Conditions\n\n**Permission**: add_work_packages",
"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 work package\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\n\n# Conditions\n\n- **Setting**: deactivate_work_package_attachments set to false in related project"
}
]
},
"addAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Permission**: edit work package",
"readOnly": true
}
]
},
"prepareAttachment": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "Attach a file to the work package\n\n# Conditions\n\n- **Setting**: direct uploads enabled",
"readOnly": true
}
]
},
"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
}
]
}
}
}
}
200
OK
{
"subject": "Upgrade hangar 25",
"lockVersion": 0,
"description": {
"format": "markdown",
"raw": "we need more place for new TIE Advanced",
"html": "<p>we need more place for new TIE Advanced</p>"
},
"scheduleManually": false,
"_links": {
"responsible": {
"href": "/api/v3/users/23",
"title": "Palpatine"
},
"assignee": {
"href": "/api/v3/users/33",
"title": "Darth Vader"
},
"priority": {
"href": "/api/v3/priorities/2",
"title": "Normal"
},
"project": {
"href": "/api/v3/projects/1",
"title": "Galactic Conquest"
},
"status": {
"href": "/api/v3/statuses/1",
"title": "New"
},
"type": {
"href": "/api/v3/types/11",
"title": "DeathStarUpgrades"
},
"version": {
"href": "/api/v3/versions/1",
"title": "Version 1"
},
"parent": {
"href": "/api/v3/work_packages/1298",
"title": "ct'hulhu f'tagn"
}
}
}
WorkPackagePatchModel
{
"type": "object",
"required": [
"lockVersion"
],
"properties": {
"lockVersion": {
"type": "integer",
"description": "The version of the item as used for optimistic locking"
},
"subject": {
"type": "string",
"description": "Work package subject"
},
"description": {
"allOf": [
{
"$ref": "#/components/schemas/Formattable"
},
{
"description": "The work package description"
}
]
},
"scheduleManually": {
"type": "boolean",
"description": "If false (default) schedule automatically."
},
"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"
},
"estimatedTime": {
"type": "string",
"format": "duration",
"description": "Time a work package likely needs to be completed excluding its descendants"
},
"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",
"properties": {
"assignee": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The person that is intended to work on the work package\n\n**Resource**: User"
}
]
},
"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"
}
]
},
"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"
}
]
},
"status": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "The current status of the work package\n\n**Resource**: Status"
}
]
},
"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"
}
]
}
}
}
},
"examples": [
{
"subject": "Upgrade hangar 25",
"lockVersion": 0,
"description": {
"format": "markdown",
"raw": "we need more place for new TIE Advanced",
"html": "<p>we need more place for new TIE Advanced</p>"
},
"scheduleManually": false,
"_links": {
"responsible": {
"href": "/api/v3/users/23",
"title": "Palpatine"
},
"assignee": {
"href": "/api/v3/users/33",
"title": "Darth Vader"
},
"priority": {
"href": "/api/v3/priorities/2",
"title": "Normal"
},
"project": {
"href": "/api/v3/projects/1",
"title": "Galactic Conquest"
},
"status": {
"href": "/api/v3/statuses/1",
"title": "New"
},
"type": {
"href": "/api/v3/types/11",
"title": "DeathStarUpgrades"
},
"version": {
"href": "/api/v3/versions/1",
"title": "Version 1"
},
"parent": {
"href": "/api/v3/work_packages/1298",
"title": "ct'hulhu f'tagn"
}
}
}
]
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: edit work package, assign version, change work package status, 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
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- the 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",