Update work package
update_work_packageChange any writable field of an OpenProject work package — assignee, status, dates, parent, progress, or custom fields. Optimistic locking prevents overwriting concurrent edits.
Instructions
Change any writable field of a work package, with optimistic locking done properly.
Use it to assign or unassign, move a status forward, re-schedule, re-parent, set progress or write custom fields. Every convenience the old tooling spread across a dozen tools is a parameter here.
Returns the updated work package in full detail, including the new lock_version to use
for a follow-up edit.
Pitfalls: omitted parameters are left alone, while passing null clears a field
(assignee, responsible, version, parent, dates, description). A 409 error means somebody
else changed the work package first — the error carries the fresh lock_version and the
conflicting fields, so re-read, decide, and retry deliberately rather than blindly.
Status changes are validated against the workflow, so an invalid transition lists the
allowed targets.
Ids come from get_work_package / list_work_packages; status, priority, type and
version values come from get_project_metadata.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Work package id to change (the #1234 number). | |
| date | No | Milestone date (YYYY-MM-DD); only valid on milestone types. | __unchanged__ |
| type | No | New type as a name or numeric id. Cannot be cleared. | |
| notify | No | Send OpenProject notification emails for this change. | |
| status | No | New status as a name or numeric id. Validated through the form endpoint, so an invalid workflow transition comes back listing the statuses that *are* reachable from the current one. | |
| subject | No | New title. Omit to leave unchanged; cannot be cleared. | |
| version | No | Numeric version / sprint id; null removes it from the version. | __unchanged__ |
| assignee | No | Numeric user id to assign. Omit to leave unchanged; pass null (or 'none') to unassign — that sends a null href rather than a bogus user id. | __unchanged__ |
| due_date | No | ISO date (YYYY-MM-DD); null clears it. | __unchanged__ |
| priority | No | New priority as a name or numeric id. | |
| parent_id | No | Re-parent this work package under another id; null detaches it and makes it top level. This is the only hierarchy tool — there is no separate set/remove-parent tool. | __unchanged__ |
| start_date | No | ISO date (YYYY-MM-DD); null clears it. | __unchanged__ |
| description | No | New markdown body. Omit to leave unchanged; pass null to empty it. Replaces the whole description — read it with get_work_package first if you mean to append. | __unchanged__ |
| responsible | No | Numeric user id of the accountable person; null clears it. | __unchanged__ |
| lock_version | No | The `lock_version` you read from get_work_package. Pass it and the write fails loudly (409) if somebody else edited the work package in the meantime. Omit it and the current version is fetched and echoed — still safe, just one more round trip and a slightly wider conflict window. | |
| custom_fields | No | Custom field writes keyed by wire key or display name, e.g. {'Severity': 'High'}. Unknown or non-writable keys fail with the valid keys listed. Only the keys you pass are touched. | |
| estimated_hours | No | Estimate in hours as a decimal. | |
| percentage_done | No | Progress 0-100. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Work package id. | |
| date | No | Milestone date (ISO YYYY-MM-DD); null for non-milestones. | |
| type | No | Work package type. | |
| notes | No | Degradation notes for this result. | |
| author | No | Creating user. | |
| parent | No | Parent work package. | |
| status | No | Status. | |
| project | No | Owning project. | |
| subject | No | Subject line. | |
| version | No | Version / sprint. | |
| assignee | No | Assigned user or group. | |
| category | No | Category. | |
| due_date | No | ISO date (YYYY-MM-DD). | |
| priority | No | Priority. | |
| available | No | Feature availability for this WP: dev links, meetings, files. | |
| created_at | No | ISO 8601 UTC timestamp. | |
| display_id | No | Human-facing id as the instance renders it. Matches the numeric id unless the instance uses semantic identifiers (17.x, e.g. 'PROJ-42'); null when the instance predates it. | |
| start_date | No | ISO date (YYYY-MM-DD). | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| description | No | Description as markdown (raw); html is dropped. | |
| responsible | No | Accountable user. | |
| spent_hours | No | Logged time in hours. | |
| lock_version | No | Optimistic-locking version; pass to update_work_package. | |
| custom_fields | No | Always a list; empty when none are set. | |
| project_phase | No | Project phase this work package sits in (16.1+, only when phases are active in the project and visible to this user); details via get_project_phase. | |
| estimated_hours | No | Estimate in hours. | |
| percentage_done | No | Progress, 0-100. |