search_work_packages
Search work packages by subject text or numeric ID across projects, and filter by project, status, assignee, priority, or date ranges.
Instructions
Search work packages by free text, optionally scoped to a project.
query 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, query is always also resolved directly (numeric id or display id like "PROJ-42") the same way get_work_package does. When that resolves to a work package that also satisfies every other filter given here (project/status/assignee/dates/ 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 accept YYYY-MM-DD format:
created_on/updated_on/due_on: exact date match
created_between/updated_between/due_between: inclusive date range [start, end] Cannot specify both _on and _between for the same field.
sort_by accepts a list of sort criteria in format "field:direction" (e.g., ["status:desc", "priority:asc"]). Direction defaults to "asc" if omitted. Common sortable fields: id, subject, status, priority, type, assignee, author, created_at, updated_at, start_date, due_date.
group_by accepts a field name to group results by (e.g., "status", "assignee"). Common groupable fields: status, priority, type, assignee, author, version, category.
select restricts each result row to the given fields (e.g. ["id", "subject", "status"]); an invalid name returns the allowed set. Common fields: id, display_id, subject, type, status, priority, assignee, project, version, parent_id, parent_display_id, start_date, due_date, estimated_time, spent_time, created_at, updated_at, author, category, description, schedule_manually, derived_start_date, derived_due_date, percentage_done, derived_percentage_done, readonly, ignore_non_working_days. parent_display_id is only populated on OpenProject 17.5+ (semantic mode); it stays null on older/classic instances even when parent_id is set.
limit is capped at OPENPROJECT_MAX_PAGE_SIZE (default 50); pass the returned next_offset as the next call's offset to page past the cap. total is the real matching count only when the query is provably restricted to OPENPROJECT_READ_PROJECTS server-side — scope is unrestricted, or an explicit project was given. Otherwise (no project, restricted scope) total falls back to this page's item count, and next_offset/truncated are based on whether this page came back full rather than the server's own total, so nothing here ever reveals how many matches exist in projects you can't see. Because of this, total can read 0 while next_offset is still non-null (a restrictive scope filtered out every match on this page, but the raw server page was full) — that is not an inconsistency, keep paging via next_offset rather than stopping on a low/zero total. Page until next_offset is null either way.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| due_on | No | ||
| offset | No | ||
| select | No | ||
| status | No | ||
| project | No | ||
| sort_by | No | ||
| assignee | No | ||
| group_by | No | ||
| priority | No | ||
| open_only | No | ||
| created_on | No | ||
| updated_on | No | ||
| assignee_me | No | ||
| due_between | No | ||
| created_between | No | ||
| updated_between | No |