Create work package
create_work_packageCreate tasks, bugs, subtasks, or milestones in OpenProject with pre-flight validation. Invalid inputs return structured errors listing allowed values before anything is saved.
Instructions
Create a work package, validated through OpenProject's own form endpoint first.
Use it for new tasks, bugs, subtasks (parent_id) and milestones (date). The form
pre-flight is what makes failures useful: an invalid status, a missing required custom
field or a type the project does not enable comes back as structured violations with the
allowed values, before anything is written.
Returns the created work package in full detail, including its new id, lock_version
and resolved custom fields.
Pitfalls: type, status and priority take names or ids, but versions, assignees and
parents need numeric ids. Milestone types reject start_date/due_date — use date.
Custom fields must exist on the project/type schema; check get_work_package_schema when
unsure.
To change it afterwards use update_work_package; to attach a file to an existing work
package use upload_attachment.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | The single ISO date of a **milestone**. Milestones carry `date` instead of start_date/due_date; passing both shapes is rejected locally. | |
| type | Yes | Work package type as a **name or numeric id** ('Task', 'Bug', 'Milestone', or 7). Names resolve against this instance's types; an unknown or ambiguous name fails with the valid values listed. | |
| notify | No | Send OpenProject notification emails for this creation. | |
| status | No | Status name or numeric id. Omit to take the type's default status — do not guess an id. | |
| project | Yes | Numeric project id or project identifier (URL slug). Both come from list_projects. | |
| subject | Yes | The title. Required and must not be blank. | |
| version | No | Numeric version / sprint id; from get_project_metadata. | |
| assignee | No | Numeric user id to assign. 'me' is not accepted in writes — call get_instance_info for the current user's id. | |
| due_date | No | ISO date (YYYY-MM-DD). Not valid on milestone types. | |
| priority | No | Priority name or numeric id ('High', 'Normal', or 8). Omit for the instance default; priority ids differ per instance. | |
| parent_id | No | Create this as a child of an existing work package id. | |
| start_date | No | ISO date (YYYY-MM-DD). Not valid on milestone types. | |
| description | No | Body text in markdown. Omit for an empty description. | |
| responsible | No | Numeric user id of the accountable person. | |
| custom_fields | No | Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields accept option ids or option names. Unknown or ambiguous keys fail with the valid keys listed — nothing is ever silently dropped. get_work_package_schema shows what this project and type accept. | |
| estimated_hours | No | Estimate in hours as a decimal (7.5 = seven and a half). | |
| attachment_paths | No | Local file paths to attach. Files upload uncontainered first and are claimed by the new work package, which is the flow that works even when the author lacks edit permission. Only usable when the server shares a filesystem with you (stdio transport). |
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. |