search_work_packages
Find work packages by free text or ID, optionally scoped to a project, and resolve exact references with filters for status, assignee, priority, and dates.
Instructions
Search work packages by free text, optionally scoped to a project.
search matches only the work package subject and numeric ID (OpenProject's native subject_or_id full-text filter); it does NOT match version, category, description, or other linked-resource fields. To filter by version, use list_work_packages(version=..., project=...) instead.
In parallel with that text/id search, a search shaped like a work package reference (a numeric id or a display id like "PROJ-42", but not a date such as 2026-10-15) is also resolved directly the same way get_work_package does; other text is never looked up as an id. When that resolves to a work package that also satisfies every other filter given here (project/status/assignee/dates/ custom fields/etc.), it's returned separately as exact_match; never folded into results, and never counted toward total/count/pagination, since a single extra item can't be paginated consistently. Absent (not present in the response at all) when nothing resolves, when the resolved item fails a filter, or when it's already present in results via the text match. select applies to exact_match the same way it applies to each results row.
Without project, the search runs globally across every project readable under OPENPROJECT_READ_PROJECTS, not just one project; pass project explicitly to scope results to it.
Set status to restrict results to an exact OpenProject status name or numeric ID, not a meta-value like 'open'/'closed'. Set open_only=true to return only open (not-closed) work packages. Set assignee_me=true to return only work packages assigned to the current user.
assignee filters by any user (username, id, or "me"). assignee_me takes precedence.
priority filters by priority name or numeric ID (case-insensitive).
Date filters, overdue_only/due_within_days, select, pagination (offset/limit/total), include_sums, and each result's custom_fields/custom_comments (raw-key custom-field values/comments, capped and hide-matched exactly as documented) all work exactly as documented on list_work_packages; see that tool's docstring for the full field lists and semantics. sort_by and group_by take the same fields and are described by their own parameters. One difference: total is the real matching count only when scope is unrestricted or an explicit project was given (list_work_packages's server-side allowed-project filter for the no-project+restricted-scope case does not apply here); otherwise total/groups/total_sums fall back to this page's data, same safety guarantee either way.
custom_field_filters filters by custom field value(s); see list_work_packages's docstring for the full parameter documentation (identical shape and semantics on both tools).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, capped at OPENPROJECT_MAX_PAGE_SIZE. | |
| due_on | No | ||
| offset | No | 1-based page number; pass the previous result's next_offset. | |
| search | Yes | ||
| select | No | Fields to return; a requested unset field comes back as null. Allowed: assignee, author, category, created_at, custom_comments, custom_comments_truncated, custom_fields, custom_fields_truncated, derived_due_date, derived_estimated_time, derived_percentage_done, derived_remaining_time, derived_start_date, description, description_length, description_truncated, display_id, due_date, duration, estimated_time, has_description, has_project_attributes, id, ignore_non_working_days, parent_display_id, parent_id, percentage_done, priority, project, project_phase, readonly, remaining_time, responsible, schedule_manually, spent_time, sprint, start_date, status, subject, target_versions, type, updated_at, version. | |
| status | No | ||
| project | No | Project identifier, id, or name; a unique part of a name or identifier also matches. | |
| sort_by | No | Sort criteria as "field:direction" or "field-direction" (e.g. ["status:desc", "priority-asc"]); the direction defaults to asc. Fields: assigned_to, assignee, author, backlog_bucket, category, created_at, done_ratio, due_date, duration, estimated_hours, estimated_time, id, observed_in_versions, percentage_done, position, priority, project, project_phase, remaining_hours, remaining_time, responsible, sprint, start_date, status, story_points, subject, target_versions, type, updated_at, version, or a custom field's cf_<id>. Newer columns need an OpenProject release: project_phase 16.1+, sprint 17.4+, backlog_bucket 17.6+, target_versions 17.8+, observed_in_versions 17.9+; target_versions is version under its newer name. sprint and backlog_bucket also need the Backlogs module in a project where you may view sprints. | |
| assignee | No | ||
| group_by | No | One field to group the results by: assigned_to, assignee, author, backlog_bucket, category, done_ratio, observed_in_versions, percentage_done, priority, project, project_phase, responsible, sprint, status, target_versions, type, version, or a custom field's cf_<id>. Newer columns need an OpenProject release: project_phase 16.1+, sprint 17.4+, backlog_bucket 17.6+, target_versions 17.8+, observed_in_versions 17.9+; target_versions is version under its newer name. sprint and backlog_bucket also need the Backlogs module in a project where you may view sprints. | |
| priority | No | ||
| open_only | No | ||
| created_on | No | ||
| updated_on | No | ||
| assignee_me | No | ||
| due_between | No | ||
| include_sums | No | ||
| overdue_only | No | ||
| created_between | No | ||
| due_within_days | No | ||
| updated_between | No | ||
| custom_field_filters | No |