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 | |
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; 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; 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’s 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’s descendants. If manual scheduleManually is active, the two dates can deviate. | Date | READ | ||
estimatedTime | Time a work package likely needs to be completed excluding its descendants | Duration | READ / WRITE | ||
derivedEstimatedTime | Time a work package likely needs to be completed including its descendants | Duration | READ | ||
spentTime | The time booked for this work package by users working on it | Duration | READ | Permission view time entries | |
percentageDone | Amount of total completion for a work package | Integer | 0 <= x <= 100; Cannot be set for parent work packages | READ / WRITE | |
createdAt | Time of creation | DateTime | READ | ||
updatedAt | Time of the most recent change to the work package | DateTime | READ |
Note that the properties listed here only cover the built-in properties of the OpenProject Core. Using plug-ins and custom fields a work package might contain various additional properties. A client can consult the schema information to which the work package links. The schema will contain information about all properties of the linking work package, including properties added by plug-ins and custom fields.
Custom fields are identified by a key in the form of customFieldN
, where N
is an integer. Depending on their type,
they can occur as properties or as linked properties. A client has to consult the schema to resolve
the human readable name of custom fields.
Properties that cannot be set directly on parent work packages are inferred from their children instead:
-
startDate
is the earliest start date from its children if manual scheduling is activated. -
dueDate
is the latest finish date from its children if manual scheduling is activated. -
estimatedTime
is the sum of estimated times from its children -
percentageDone
is the weighted average of the sum of its children percentages done. The weight is given by the average of its children estimatedHours. However, if the percentage done is given by a work package’s status, then only the status matters and no value is inferred.
startDate
can also not be earlier than a finish date of any predecessor.
While attachments are returned as a link which’s content is to be fetched separately, clients can choose to replace the work package’s attachments by providing an array of already uploaded Attachment resources on create and update. The attachments the work package has had prior to the request will be removed.
Work Package
- Parameters
- id
integer
(required) Example: 1Work package id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_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, "startDate": null, "dueDate": null, "derivedStartDate": null, "derivedDueDate": null, "estimatedTime": "PT2H", "derivedEstimatedTime": "PT10H", "percentageDone": 0, "customField1": "Foo", "customField2": 42, "createdAt": "2014-08-29T12:40:53Z", "updatedAt": "2014-08-29T12:44:41Z" }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
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.
- Parameters
- id
integer
(required) Example: 1Work package id
- notify
boolean
(optional) Default: true Example: falseIndicates 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.
- RequestToggle details
Headers
Content-Type: application/json
Body
{ "lockVersion": 13, "subject": "Lorem", "_links": { "parent": { "href": "/api/v3/work_packages/42" } } }
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_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, "startDate": null, "dueDate": null, "derivedStartDate": null, "derivedDueDate": null, "estimatedTime": "PT2H", "derivedEstimatedTime": "PT10H", "percentageDone": 0, "customField1": "Foo", "customField2": 42, "createdAt": "2014-08-29T12:40:53Z", "updatedAt": "2014-08-29T12:44:41Z" }
- Response
400
Toggle details Occurs when the client did not send a valid JSON object in the request body.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: edit work package, assign version, manage subtasks or move work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to edit the content of the work package." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
- Response
409
Toggle details Returned if the resource was changed since the client requested it. This is determined using the
lockVersion
property.Headers
Content-Type: application/hal+json
Body
{ "_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." }
- Response
422
Toggle details 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
)
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "The subject might not be blank.", "_embedded": { "details": { "attribute": "Subject" } } }
-
Deletes the work package, as well as:
-
all associated time entries
-
its hierarchy of child work packages
- Parameters
- id
integer
(required) Example: 1Work package id
- Response
204
Toggle details 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.
Headers
Content-Type: application/hal+json
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: delete work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to delete this work package." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Work Package Schema
- Parameters
- identifier
string
(required) Example: 12-13Identifier of the schema
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the work package schema resource. See [Schemas](schemas) section for details.
- Response
404
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified schema does not exist." }
Work Package Schemas
List work package schemas.
- Parameters
- filters
string
(required) Example: [{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:
- id: The schema’s id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_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" } } <snip> }, { "_type": "Schema", "_links": { "self": { "href": "/api/v3/work_packages/schemas/7-6" } } <snip> } ] } }
- Response
400
Toggle details Returned if the client sends invalid request.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery", "message": "Unknown filter." }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: View work packages in any project.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to list schemas." }
Work Package Edit Form
This endpoint returns a form to allow a guided modification of an existing work package.
For more details and all possible responses see the general specification of Forms.
- Parameters
- id
integer
(required) Example: 1ID of the work package being modified
- Response
200
Toggle details Headers
Content-Type: application/hal+json
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: edit work package, assign version, manage subtasks or move work package
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to edit the specified work package." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Work Packages
- Parameters
- offset
integer
(optional) Default: 1 Example: 25Page number inside the requested collection.
- pageSize
integer
(optional) Default: DEPENDING ON CONFIGURATION Example: 25Number of elements to display per page.
- filters
string
(optional) Default: [{ "status_id": { "operator": "o", "values": null }}] Example: [{ "type_id": { "operator": "=", "values": ['1', '2'] }}]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 (
[]
).- sortBy
string
(optional) Default: ["id", "asc"] Example: [["status", "asc"]]JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.
- groupBy
string
(optional) Example: statusThe column to group by.
- showSums
boolean
(optional) Default: false Example: trueIndicates whether properties should be summed up if they support it.
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/work_packages" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "WorkPackage", "_links": { "self": { "href": "/api/v3/work_packages/1" } }, "id": 1, "subject": "Skipped other properties for brevity" }, { "_type": "WorkPackage", "_links": { "self": { "href": "/api/v3/work_packages/2" } }, "id": 2, "subject": "Skipped other properties for brevity" } ] } }
- Response
400
Toggle details Returned if the client sends a query parameter, that the server knows, but does not understand. E.g. by providing a syntactically incorrect
filters
parameter.Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery", "message": "Operator can't be blank." }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: view work packages (globally or in any project)
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to see work packages." }
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.
- Parameters
- notify
boolean
(optional) Default: true Example: falseIndicates 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.
- RequestToggle details
Headers
Content-Type: application/json
Body
{ "subject": "Lorem", "customField41": 8, "startDate": "2048-01-03", "_links": { "project": { "href": "/api/v3/project/42" }, "type": { "href": "/api/v3/type/123" }, "assignee": { "href": "/api/v3/users/8" }, "customField32": { "href": "/api/v3/users/3" } } }
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_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, "startDate": null, "dueDate": null, "derivedStartDate": null, "derivedDueDate": null, "estimatedTime": "PT2H", "derivedEstimatedTime": "PT10H", "percentageDone": 0, "customField1": "Foo", "customField2": 42, "createdAt": "2014-08-29T12:40:53Z", "updatedAt": "2014-08-29T12:44:41Z" }
- Response
400
Toggle details Occurs when the client did not send a valid JSON object in the request body.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." }
- Response
403
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to add work packages to this project." }
- Response
404
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified project does not exist." }
- Response
422
Toggle details 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
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "The subject might not be blank.", "_embedded": { "details": { "attribute": "Subject" } } }
-
Work Package Create Form
This endpoint returns a form to allow a guided creation of a new work package. The returned form will be pre-filled with default values for every property, if available.
For more details and all possible responses see the general specification of Forms. A project link must be set when creating work packages through this route.
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the form resource that was created. See [Forms](/api/forms) section for details.
Work Packages by Project
- Parameters
- id
integer
(required) Example: 1Project id
- offset
integer
(optional) Default: 1 Example: 25Page number inside the requested collection.
- pageSize
integer
(optional) Default: DEPENDING ON CONFIGURATION Example: 25Number of elements to display per page.
- filters
string
(optional) Default: [{ "status_id": { "operator": "o", "values": null }}] Example: [{ "type_id": { "operator": "=", "values": ['1', '2'] }}]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 (
[]
).- sortBy
string
(optional) Default: ["id", "asc"] Example: [["status", "asc"]]JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.
- groupBy
string
(optional) Example: statusThe column to group by.
- showSums
boolean
(optional) Default: false Example: trueIndicates whether properties should be summed up if they support it.
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/projects/14/work_packages" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "WorkPackage", "_links": { "self": { "href": "/api/v3/work_packages/1" } }, "id": 1, "subject": "Skipped other properties for brevity" }, { "_type": "WorkPackage", "_links": { "self": { "href": "/api/v3/work_packages/2" } }, "id": 2, "subject": "Skipped other properties for brevity" } ] } }
- Response
400
Toggle details Returned if the client sends a query parameter, that the server knows, but does not understand. E.g. by providing a syntactically incorrect
filters
parameter.Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery", "message": "Operator can't be blank." }
- Response
403
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to see the work packages of this project." }
- Response
404
Toggle details Returned if the project does not exist or the client does not have sufficient permissions to see it.
Required permission: view project
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified project does not exist." }
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.
- Parameters
- id
integer
(required) Example: 1Project id
- notify
boolean
(optional) Default: true Example: falseIndicates 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.
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_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, "startDate": null, "dueDate": null, "derivedStartDate": null, "derivedDueDate": null, "estimatedTime": "PT2H", "derivedEstimatedTime": "PT10H", "percentageDone": 0, "customField1": "Foo", "customField2": 42, "createdAt": "2014-08-29T12:40:53Z", "updatedAt": "2014-08-29T12:44:41Z" }
- Response
400
Toggle details Occurs when the client did not send a valid JSON object in the request body.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." }
- Response
403
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to add work packages to this project." }
- Response
404
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified project does not exist." }
- Response
422
Toggle details 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
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "The subject might not be blank.", "_embedded": { "details": { "attribute": "Subject" } } }
-
Work Package Create Form
This endpoint returns a form to allow a guided creation of a new work package. The returned form will be pre-filled with default values for every property, if available.
For more details and all possible responses see the general specification of Forms.
- Parameters
- id
integer
(required) Example: 1ID of the project in which the work package will be created
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the form resource that was updated. See [Forms](/api/forms) section for details.
Relations
When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a Relation can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.
- Parameters
- work_package_id
integer
(required) Example: 1Work package id
- Request
Create Relation
Toggle details Headers
Content-Type: application/json
Body
{ "_links": { "from": { "href": "/api/v3/work_packages/42" }, "to": { "href": "/api/v3/work_packages/84" } } "type": "duplicates", "description": "This is the same thing. Let's track it in one place only, shall we?" }
- Response
201
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the relation resource. See [Relations](relations) for more information.
- Response
400
Toggle details Occurs when the client did not send a valid JSON object in the request body.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: manage work package relations
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to create a relation." }
- Response
409
Toggle details Returned if there already exists a relation between the given work packages of any type or if the relation is not allowed.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict", "message": "Couldn't update the resource because of conflicting modifications." }
- Response
422
Toggle details Returned if:
-
the client tries to write a read-only property (
PropertyIsReadOnly
) -
a constraint for a property was violated (
PropertyConstraintViolation
) -
the client provides a link to an invalid resource (
ResourceTypeMismatch
)
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation", "message": "Delay must be a number greater than or equal to 0", "_embedded": { "details": { "attribute": "delay" } } }
-
Lists all relations this work package is involved in.
- Parameters
- work_package_id
integer
(required) Example: 1Work package id
- Response
302
Toggle details Headers
Content-Type: text/plain
Location: /api/v3/relations?involved={work_package_id}Body
You are being redirected to /api/v3/relations?involved={work_package_id}
Work Package Relation Form
- Parameters
- id
integer
(required) Example: 1ID of the relation being modified
- RequestToggle details
Body
{ "_type": "Relation", "type": "follows", "from": { "href": "/api/v3/work_packages/3493" }, "to": { "href": "/api/v3/work_packages/4582" }, "description": "let it rest for 3 days", "delay": 3 }
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/relations/form" }, "validate": { "href": "/api/v3/relations/form", "method": "POST" }, "commit": { "href": "/api/v3/relations", "method": "PATCH" } }, "_type": "Form", "_embedded": { "payload": { "_links": { "from": { "href": "/api/v3/work_packages/4534" }, "to": { "href": "/api/v3/work_packages/3857" } }, "_type": "WorkPackage", "type": "follows", "delay": 3, "description": "let it rest for 3 days" }, "schema": { "_type": "Schema", "id": { "name": "ID", "type": "Integer", "writable": false }, "type": { "name": "Type", "type": "String", "writable": true, "allowedValues": [ "relates", "duplicates", "duplicated", "blocks", "blocked", "precedes", "follows", "includes", "partof", "requires", "required" ] }, "reverseType": { "name": "Reverse Type", "type": "String", "writable": false }, "description": { "name": "Description", "type": "String", "writable": true }, "from": { "_links": { "allowedValues": [ { "href": "/api/v3/work_packages/{id}" } ] }, "name": "From work package", "type": "WorkPackage", "writable": true }, "to": { "_links": { "allowedValues": { "href": "/api/v3/work_packages/{id}/available_relation_candidates", "title": "Available work packages to relate to" } }, "name": "To work package", "type": "WorkPackage", "writable": true }, "delay": { "name": "Delay", "type": "Integer", "writable": true } }, "validationErrors": { "from": { "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError", "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors." } } } }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: manage work package relations
Note that you will only receive this error, if you are at least allowed to see the involved work packages.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to edit the specified relation." }
- Response
404
Toggle details Returned if the relation does not exist or the client does not have sufficient permissions to see it.
Required permission: view (involved) work package(s), manage work package relations
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified relation does not exist." }
Watchers
- Parameters
- work_package_id
integer
(required) Example: 1Work package id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/work_packages/14/watchers" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "User", "_links": { "self": { "href": "/api/v3/users/1", "title": "John Sheppard - j.sheppard" }, "showUser": { "href": "/users/1", "type": 'text/html' }, "lock": { "href": "/api/v3/users/1/lock", "title": "Set lock on j.sheppard" "method": "POST" }, "delete": { "href": "/api/v3/users/1", "title": "Delete j.sheppard" "method": "DELETE" } }, "id": 1, "login": "j.sheppard", "firstName": "John", "lastName": "Sheppard", "mail": "shep@mail.com", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }, { "_type": "User", "_links": { "self": { "href": "/api/v3/users/2", "title": "Jim Sheppard - j.sheppard2" }, "lock": { "href": "/api/v3/users/2/lock", "title": "Set lock on j.sheppard2" "method": "POST" }, "delete": { "href": "/api/v3/users/2", "title": "Delete j.sheppard2" "method": "DELETE" } }, "id": 2, "login": "j.sheppard2", "firstName": "Jim", "lastName": "Sheppard", "mail": "shep@mail.net", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }] } }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: view work package watchers
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to see the watchers of this work package." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Note that you will effectively not be able to see the watchers of a work package without being able to see the work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Adds a watcher to the specified work package.
The request is expected to contain a single JSON object, that contains a link object under the user
key.
The response will be user added as watcher.
In case the user was already watching the work package an HTTP 200
is returned, an
HTTP 201
if the user was added as a new watcher.
- Parameters
- work_package_id
integer
(required) Example: 1Work package id
- RequestToggle details
Headers
Content-Type: application/json
Body
{ "user": { "href": "/api/v3/users/1" } }
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the user resource
- Response
201
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the user resource
- Response
400
Toggle details Occurs when the client did not send a valid JSON object in the request body.
For example:
-
The request did not contain a single JSON object
-
The JSON object did not contain the key
user
-
The value of
users
was not a link object
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." }
-
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permissions:
-
view work package (for self)
-
add work package watchers (for other users)
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to add watchers to this work package." }
-
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
- Response
422
Toggle details Returned if:
-
the client tries to specify a link to a resource that is not a user (
ResourceTypeMismatch
) -
the user specified is not allowed to watch that work package (
PropertyConstraintViolation
) -
the user specified does not exist (
PropertyConstraintViolation
)
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:ResourceTypeMismatch", "message": "Expected resource of type 'User', but got a 'Status'.", }
-
Remove Watcher
Removes the specified user from the list of watchers for the given work package.
If the request succeeds, the specified user is not watching the work package anymore.
Note: This might also be the case, if the specified user did not watch the work package prior to the request.
- Parameters
- work_package_id
integer
(required) Example: 1Work package id
- id
integer
(required) Example: 1User id
- Response
204
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: delete work package watchers
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to remove watchers from this work package." }
- Response
404
Toggle details Returned in one of the following cases:
Either the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Or the specified user does not exist at all.
Note that you will effectively not be able to change the watchers of a work package without being able to see the work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Available relation candidates
Lists work packages with which this work package can be in a relation. Only sound candidates are returned. For instance a work package cannot stand in relation to itself, and a work package that follows another cannot precede it.
Candidates can be filtered. Most commonly one will want to filter by subject.
You can do this through the filters
parameter which works just like the work package index.
For instance to find all work packages with “rollout” in their subject:
?filters=[{"subject":{"operator":"~","values":["rollout"]}}]
For convenience there is also a simple query
parameter which is a shortcut for listing work packages
whose ID or subject contain the given string.
While the endpoint does support the pageSize parameter to limit the number of results it does not support the offset parameter.
?query=112
- Parameters
- pageSize
integer
(optional) Example: 25Maximum number of candidates to list (default 10)
- filters
string
(optional) Example: [{ "status_id": { "operator": "o", "values": null } }]JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint.
- query
string
(optional) Example: "rollout"Shortcut for filtering by ID or subject
- type
string
(optional) Example: "follows"Type of relation to find candidates for (default “relates”)
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/projects/14/work_packages" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "WorkPackage", "_links": { "self": { "href": "/api/v3/work_packages/1" } }, "id": 1, "subject": "Skipped other properties for brevity" }, { "_type": "WorkPackage", "_links": { "self": { "href": "/api/v3/work_packages/2" } }, "id": 2, "subject": "Skipped other properties for brevity" } ] } }
Available Watchers
Gets a list of users that are able to be watchers of the specified work package.
- Parameters
- id
integer
(required) Example: 1work package id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/work_packages/1/available_watchers" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "User", "_links": { "self": { "href": "/api/v3/users/1", "title": "John Sheppard - j.sheppard" }, "lock": { "href": "/api/v3/users/1/lock", "title": "Set lock on j.sheppard" "method": "POST" }, "delete": { "href": "/api/v3/users/1", "title": "Delete j.sheppard" "method": "DELETE" } }, "id": 1, "login": "j.sheppard", "firstName": "John", "lastName": "Sheppard", "email": "shep@mail.com", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }, { "_type": "User", "_links": { "self": { "href": "/api/v3/users/2", "title": "Jim Sheppard - j.sheppard2" }, "lock": { "href": "/api/v3/users/2/lock", "title": "Set lock on j.sheppard2" "method": "POST" }, "delete": { "href": "/api/v3/users/2", "title": "Delete j.sheppard2" "method": "DELETE" } }, "id": 2, "login": "j.sheppard2", "firstName": "Jim", "lastName": "Sheppard", "email": "shep@mail.net", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }] } }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: add work package watchers
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not authorized to access this resource." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Available Projects
Gets a list of projects that are available as projects to which the work package can be moved.
- Parameters
- id
integer
(required) Example: 1work package id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/work_packages/5/available_projects" } }, "_type": "Collection", "total": 2, "count": 2, "_embedded": { "elements": [ { "_type": "Project", "_links": { "self": { "href": "/api/v3/projects/6", "title": "A project" }, "editWorkPackage": { "href": "/api/v3//work_packages/{work_package_id}/form", "templated": true, "method": "post" }, "createWorkPackage": { "href": "/api/v3/projects/6/work_packages/form", "method": "post" }, "createWorkPackageImmediate": { "href": "/api/v3/projects/6/work_packages", "method": "post" }, "categories": { "href": "/api/v3/projects/6/categories" }, "versions": { "href": "/api/v3/projects/6/versions" } }, "id": 6, "identifier": "a_project", "name": "A project", "description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.", "createdAt": "2015-07-06T13:28:14+00:00", "updatedAt": "2015-10-01T09:55:02+00:00", "type": "Customer Project" }, { "_type": "Project", "_links": { "self": { "href": "/api/v3/projects/14", "title": "Another project" }, "createWorkPackage": { "href": "/api/v3/projects/14/work_packages/form", "method": "post" }, "createWorkPackageImmediate": { "href": "/api/v3/projects/14/work_packages", "method": "post" }, "categories": { "href": "/api/v3/projects/14/categories" }, "versions": { "href": "/api/v3/projects/14/versions" } }, "id": 14, "identifier": "another_project", "name": "Another project", "description": "", "createdAt": "2016-02-29T12:50:20+00:00", "updatedAt": "2016-02-29T12:50:20+00:00", "type": null }] } } }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: edit work package
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not authorized to access this resource." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Revisions
Gets a list of revisions that are linked to this work package, e.g., because it is referenced in the commit message of the revision. Only linked revisions from repositories are shown if the user has the view changesets permission in the defining project.
- Parameters
- id
integer
(required) Example: 1work package id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/work_packages/42/revisions" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "Revision", "_links": { "self": { "href": "/api/v3/revisions/13", }, "project": { "href": "/api/v3/projects/1", "title": "A Test Project }, "author": { "href": "/api/v3/users/1", "title": "John Sheppard - j.sheppard" }, "showRevision": { "href": "/projects/identifier/repository/revision/11f4b07" } }, "id": 13, "identifier": "11f4b07dff4f4ce9548a52b7d002daca7cd63ec6", "formattedIdentifier": "11f4b07", "authorName": "John Sheppard", "message": { "format": "plain", "raw": "This revision provides new features\n\nAn elaborate description", "html": "<p>This revision provides new features<br/><br/>An elaborate description</p>" }, "createdAt": "2015-07-21T13:36:59Z", }, { "_type": "Revision", "_links": { "self": { "href": "/api/v3/revisions/14", }, "project": { "href": "/api/v3/projects/1", "title": "A Test Project }, "author": { "href": "/api/v3/users/2", "title": "Jim Sheppard - j.sheppard" } "showRevision": { "href": "/projects/identifier/repository/revision/029ed72a" } }, "id": 13, "identifier": "029ed72a3b7b7c4ab332b1f6eaa6576e7c946059", "formattedIdentifier": "029ed72a", "authorName": "j1msheppard", "message": { "format": "plain", "raw": "This revision fixes some stuff\n\nMore information here", "html": "<p>This revision fixes some stuff<br/><br/>More information here</p>" }, "createdAt": "2015-06-30T08:47:00Z", }] } }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: view work packages for the project the work package is contained in.
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to see linked revisions for this work package." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work project does not exist." }
Work Package activities
- Parameters
- id
integer
(required) Example: 1Work package id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/work_packages/1/revisions" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "Activity", "_links": { "self": { "href": "/api/v3/activity/1" }, "workPackage": { "href": "/api/v3/work_packages/1" }, "user": { "href": "/api/v3/users/1" } }, "id": 1, "details": [], "comment": { "format": "markdown", "raw": "Lorem ipsum dolor sit amet.", "html": "<p>Lorem ipsum dolor sit amet.</p>" }, "createdAt": "2014-05-21T08:51:20Z", "version": 1 }, { "_type": "Activity", "_links": { "self": { "href": "/api/v3/activity/2" }, "workPackage": { "href": "/api/v3/work_packages/1" }, "user": { "href": "/api/v3/users/1" } }, "id": 2, "details": [], "comment": { "format": "markdown", "raw": "Lorem ipsum dolor sit amet.", "html": "<p>Lorem ipsum dolor sit amet.</p>" }, "createdAt": "2014-05-21T08:51:22Z", "version": 2 } ] } }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Creates an activity for the selected work package and, on success, returns the updated activity.
- Parameters
- id
integer
(required) Example: 1Work package id
- notify
boolean
(optional) Default: true Example: falseIndicates 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.
- RequestToggle details
Headers
Content-Type: application/json
Body
{ "comment": { "raw": "I think this is awesome!" } }
- Response
201
Toggle details Headers
Content-Type: application/hal+json
Body
Returns the activity resource
- Response
400
Toggle details Occurs when the client did not send a valid JSON object in the request body.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody", "message": "The request body was not a single JSON object." }
- Response
403
Toggle details Returned if the client does not have sufficient permissions.
Required permission: create journals
Note that you will only receive this error, if you are at least allowed to see the corresponding work package.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to create a comment here." }
- Response
404
Toggle details Returned if the work package does not exist or the client does not have sufficient permissions to see it.
Required permission: view work package
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified work package does not exist." }
Available Assignees
Gets a list of users that can be assigned to work packages in the given project.
- Parameters
- project_id
integer
(required) Example: 1Project id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/projects/42/available_assignees" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "User", "_links": { "self": { "href": "/api/v3/users/1", "title": "John Sheppard - j.sheppard" }, "lock": { "href": "/api/v3/users/1/lock", "title": "Set lock on j.sheppard" "method": "POST" }, "delete": { "href": "/api/v3/users/1", "title": "Delete j.sheppard" "method": "DELETE" } }, "id": 1, "login": "j.sheppard", "firstName": "John", "lastName": "Sheppard", "email": "shep@mail.com", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }, { "_type": "User", "_links": { "self": { "href": "/api/v3/users/2", "title": "Jim Sheppard - j.sheppard2" }, "lock": { "href": "/api/v3/users/2/lock", "title": "Set lock on j.sheppard2" "method": "POST" }, "delete": { "href": "/api/v3/users/2", "title": "Delete j.sheppard2" "method": "DELETE" } }, "id": 2, "login": "j.sheppard2", "firstName": "Jim", "lastName": "Sheppard", "email": "shep@mail.net", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }] } }
- Response
403
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to see the assignable users for this project." }
- Response
404
Toggle details Returned if the project does not exist or the client does not have sufficient permissions to see it.
Required permission: view project
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified project does not exist." }
Available Responsibles
Gets a list of users that can be assigned as the responsible of a work package in the given project.
- Parameters
- project_id
integer
(required) Example: 1Project id
- Response
200
Toggle details Headers
Content-Type: application/hal+json
Body
{ "_links": { "self": { "href": "/api/v3/projects/42/available_responsibles" } }, "total": 2, "count": 2, "_type": "Collection", "_embedded": { "elements": [ { "_type": "User", "_links": { "self": { "href": "/api/v3/users/1", "title": "John Sheppard - j.sheppard" }, "lock": { "href": "/api/v3/users/1/lock", "title": "Set lock on j.sheppard" "method": "POST" }, "delete": { "href": "/api/v3/users/1", "title": "Delete j.sheppard" "method": "DELETE" } }, "id": 1, "login": "j.sheppard", "firstName": "John", "lastName": "Sheppard", "email": "shep@mail.com", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }, { "_type": "User", "_links": { "self": { "href": "/api/v3/users/2", "title": "Jim Sheppard - j.sheppard2" }, "lock": { "href": "/api/v3/users/2/lock", "title": "Set lock on j.sheppard2" "method": "POST" }, "delete": { "href": "/api/v3/users/2", "title": "Delete j.sheppard2" "method": "DELETE" } }, "id": 2, "login": "j.sheppard2", "firstName": "Jim", "lastName": "Sheppard", "email": "shep@mail.net", "avatar": "https://example.org/users/1/avatar", "status": "active", "createdAt": "2014-05-21T08:51:20Z", "updatedAt": "2014-05-21T08:51:20Z" }] } }
- Response
403
Toggle details 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.
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission", "message": "You are not allowed to see the users available as responsible for this project." }
- Response
404
Toggle details Returned if the project does not exist or the client does not have sufficient permissions to see it.
Required permission: view project
Headers
Content-Type: application/hal+json
Body
{ "_type": "Error", "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound", "message": "The specified project does not exist." }
Help and feedback
If you did not find what you were looking for
If you need help from the community or want to support others
If you are eligible for professional support and have more questions
REQUEST SUPPORT
If you find an easily fixable error or need for improvement in the documentation for the stable release
If you would like to suggest bigger updates or improvements to this documentation
If you want to contribute to translate this documentation to another language
If there's something you don't like or understand about this feature
If you want to propose a new feature that OpenProject does not offer yet
To further help OpenProject to shape and test new features
To view OpenProject premium features and pricing
If you want to try all premium features in the OpenProject Cloud Edition 14 days for free
If you want to try all premium features in your on premise Community installation 14 days for free