}
]
}
}
## List Work Package Schemas [GET]
List work package schemas.
+ Parameters
+ filters (required, string, `[{ "id": { "operator": "=", "values": ["12-1", "14-2"] } }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint. Currently supported filters are:
+ id: The schema's id
+ Response 200 (application/hal+json)
[Work Package Schemas][]
+ Response 400 (application/hal+json)
Returned if the client sends invalid request.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "Unknown filter."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** View work packages in any project.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to list schemas."
}
## Work Package Edit Form [/api/v3/work_packages/{id}/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](#forms).
## Work Package Edit Form [POST]
+ Parameters
+ id (required, integer, `1`) ... ID of the work package being modified
+ Response 200 (application/hal+json)
[Example Form][]
+ Response 403 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to edit the specified work package."
}
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Work Packages [/api/v3/work_packages{?notify,offset,pageSize,filters,sortBy,groupBy,showSums}]
+ Model
+ 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"
}]
}
}
## List Work Packages [GET]
+ Parameters
+ offset = `1` (optional, integer, `25`) ... Page number inside the requested collection.
+ pageSize = DEPENDING ON CONFIGURATION (optional, integer, `25`) ... Number of elements to display per page.
+ filters = `[{ "status_id": { "operator": "o", "values": null }}]` (optional, string, `[{ "type_id": { "operator": "=", "values": ['1', '2'] }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint. If no filter is to be applied, the client should send an empty array (`[]`).
+ sortBy = ["id", "asc"] (optional, string, `[["status", "asc"]]`) ... JSON specifying sort criteria.
Accepts the same format as returned by the [queries](#queries) endpoint.
+ groupBy (optional, string, `status`) ... The column to group by.
+ showSums = `false` (optional, boolean, `true`) ... Indicates whether properties should be summed up if they support it.
+ Response 200 (application/hal+json)
[Work Packages][]
+ Response 400 (application/hal+json)
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.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "Operator can't be blank."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** view work packages (globally or in any project)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to see work packages."
}
## Create Work Package [POST]
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 = `true` (optional, boolean, `false`) ... 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.
+ Response 200 (application/hal+json)
[Work Package][]
+ Response 400 (application/hal+json)
Occurs when the client did not send a valid JSON object in the request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}
+ Response 422 (application/hal+json)
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
+ 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 [/api/v3/work_packages/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](#forms).
A project link must be set when creating work packages through this route.
## Work Package Create Form [POST]
+ Response 200 (application/hal+json)
[Example Form][]
## Work Packages by Project [/api/v3/projects/{id}/work_packages{?offset,pageSize,filters,sortBy,groupBy,showSums,notify}]
+ Model
+ 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"
}]
}
}
## List Work Packages [GET]
+ Parameters
+ id (required, integer, `1`) ... Project id
+ offset = `1` (optional, integer, `25`) ... Page number inside the requested collection.
+ pageSize = DEPENDING ON CONFIGURATION (optional, integer, `25`) ... Number of elements to display per page.
+ filters = `[{ "status_id": { "operator": "o", "values": null }}]` (optional, string, `[{ "type_id": { "operator": "=", "values": ['1', '2'] }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint. If no filter is to be applied, the client should send an empty array (`[]`).
+ sortBy = ["id", "asc"] (optional, string, `[["status", "asc"]]`) ... JSON specifying sort criteria.
Accepts the same format as returned by the [queries](#queries) endpoint.
+ groupBy (optional, string, `status`) ... The column to group by.
+ showSums = `false` (optional, boolean, `true`) ... Indicates whether properties should be summed up if they support it.
+ Response 200 (application/hal+json)
[Work Packages by Project][]
+ Response 400 (application/hal+json)
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.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
"message": "Operator can't be blank."
}
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
Returned if the project does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}
## Create Work Package [POST]
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 (required, integer, `1`) ... Project id
+ notify = `true` (optional, boolean, `false`) ... 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.
+ Response 200 (application/hal+json)
[Work Package][]
+ Response 400 (application/hal+json)
Occurs when the client did not send a valid JSON object in the request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}
+ Response 422 (application/hal+json)
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
+ 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 [/api/v3/projects/{id}/work_packages/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](#forms).
## Work Package Create Form [POST]
+ Parameters
+ id (required, integer, `1`) ... ID of the project in which the work package will be created
+ Response 200 (application/hal+json)
[Example Form][]
## Relations [/api/v3/work_packages/{work_package_id}/relations]
## Create Relation [POST]
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 (required, integer, `1`) ... Work package id
+ Request Create Relation (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 (application/hal+json)
[Relation][]
+ Response 400 (application/hal+json)
Occurs when the client did not send a valid JSON object in the request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** manage work package relations
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to create a relation."
}
+ Response 409 (application/hal+json)
Returned if there already exists a relation between the given work packages of **any** type
or if the relation is not allowed.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:UpdateConflict",
"message": "Couldn't update the resource because of conflicting modifications."
}
+ Response 422 (application/hal+json)
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`)
+ 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"
}
}
}
## List relations [GET]
Lists all relations this work package is involved in.
+ Parameters
+ work_package_id (required, integer, `1`) ... Work package id
+ Response 302 (text/plain)
+ Headers
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 [/api/v3/work_packages/{id}/relations/form]
+ Model
+ 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."
}
}
}
}
## Relation create form [POST]
+ Request
{
"_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
}
+ Parameters
+ id (required, integer, `1`) ... ID of the relation being modified
+ Response 200 (application/hal+json)
[Work Package Relation Form][]
+ Response 403 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to edit the specified relation."
}
+ Response 404 (application/hal+json)
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
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified relation does not exist."
}
## Watchers [/api/v3/work_packages/{work_package_id}/watchers]
+ Model
+ 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"
}]
}
}
## List watchers [GET]
+ Parameters
+ work_package_id (required, integer, `1`) ... Work package id
+ Response 200 (application/hal+json)
[Watchers][]
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Add watcher [POST]
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 (required, integer, `1`) ... Work package id
+ Request (application/json)
{
"user": { "href": "/api/v3/users/1" }
}
+ Response 200 (application/hal+json)
[User][]
+ Response 201 (application/hal+json)
[User][]
+ Response 400 (application/hal+json)
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
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
+ Response 422 (application/hal+json)
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`)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:ResourceTypeMismatch",
"message": "Expected resource of type 'User', but got a 'Status'.",
}
## Remove Watcher [/api/v3/work_packages/{work_package_id}/watchers/{id}]
## Remove watcher [DELETE]
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 (required, integer, `1`) ... Work package id
+ id (required, integer, `1`) ... User id
+ Response 204
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Available relation candidates [/api/v3/work_packages/{id}/available_relation_candidates{?filters,query,type,pageSize}]
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
```
+ Model
+ 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 relation candidates [GET]
+ Parameters
+ pageSize (optional, integer, `25`) ... Maximum number of candidates to list (default 10)
+ filters (optional, string, `[{ "status_id": { "operator": "o", "values": null }" }]`) ... JSON specifying filter conditions.
Accepts the same format as returned by the [queries](#queries) endpoint.
+ query (optional, string, `"rollout"`) ... Shortcut for filtering by ID or subject
+ type (optional, string, `"follows"`) ... Type of relation to find candidates for (default "relates")
+ Response 200 (application/hal+json)
[Available relation candidates][]
## Available Watchers [/api/v3/work_packages/{id}/available_watchers]
+ Model
+ 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"
}]
}
}
## Available watchers [GET]
Gets a list of users that are able to be watchers of the specified work package.
+ Parameters
+ id (required, integer, `1`) ... work package id
+ Response 200 (application/hal+json)
[Available Watchers][]
+ Response 403 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Available Projects [/api/v3/work_packages/{id}/available_projects]
+ Model
+ 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"
},
"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
}]
}
}
}
## Available projects [GET]
Gets a list of projects that are available as projects to which the work package can be moved.
+ Parameters
+ id (required, integer, `1`) ... work package id
+ Response 200 (application/hal+json)
[Available Projects][]
+ Response 403 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Revisions [/api/v3/work_packages/{id}/revisions]
+ Model
+ 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": "This revision provides new features
An elaborate description
"
},
"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": "This revision fixes some stuff
More information here
"
},
"createdAt": "2015-06-30T08:47:00Z",
}]
}
}
## Revisions [GET]
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 (required, integer, `1`) ... work package id
+ Response 200 (application/hal+json)
[Revisions][]
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work project does not exist."
}
## Work Package activities [/api/v3/work_packages/{id}/activities{?notify}]
+ Model
+ 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": "Lorem ipsum dolor sit amet.
"
},
"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": "Lorem ipsum dolor sit amet.
"
},
"createdAt": "2014-05-21T08:51:22Z",
"version": 2
}]
}
}
## List work package activities [GET]
+ Parameters
+ id (required, integer, `1`) ... Work package id
+ Response 200 (application/hal+json)
[Activity][]
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Comment work package [POST]
Creates an activity for the selected work package and, on success, returns the
updated activity.
+ Parameters
+ id (required, integer, `1`) ... Work package id
+ notify = `true` (optional, boolean, `false`) ... 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.
+ Request (application/json)
{
"comment": { "raw": "I think this is awesome!" }
}
+ Response 201 (application/hal+json)
[Activity][]
+ Response 400 (application/hal+json)
Occurs when the client did not send a valid JSON object in the request body.
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
+ Response 403 (application/hal+json)
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.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to create a comment here."
}
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view work package
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Available Assignees [/api/v3/projects/{project_id}/work_packages/available_assignees]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/projects/42/work_packages/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"
}]
}
}
## Available assignees [GET]
Gets a list of users that can be assigned to work packages in the given project.
+ Parameters
+ project_id (required, integer, `1`) ... Project id
+ Response 200 (application/hal+json)
[Available Assignees][]
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
Returned if the project does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}
## Available Responsibles [/api/v3/projects/{project_id}/work_packages/available_responsibles]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/projects/42/work_packages/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"
}]
}
}
## Available responsibles [GET]
Gets a list of users that can be assigned as the responsible of a work package in the given project.
+ Parameters
+ project_id (required, integer, `1`) ... Project id
+ Response 200 (application/hal+json)
[Available Responsibles][]
+ Response 403 (application/hal+json)
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.*
+ 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 (application/hal+json)
Returned if the project does not exist or the client does not have sufficient permissions to see it.
**Required permission:** view project
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified project does not exist."
}