Search work packages
search_work_packagesFind work packages by text when you don't know their IDs. Returns compact rows and pagination; narrow by project or use list_work_packages for structured filters.
Instructions
Find work packages by text when you do not know their ids.
Use this first whenever a user names a ticket instead of numbering it, then feed the
returned id into get_work_package, update_work_package or list_work_packages.
Returns the standard list envelope: compact rows (id, subject, type, status, priority,
assignee, project, dates, progress) plus pagination with total/page/page_size/has_more.
Pitfalls: search filters, it does not rank, so a broad query returns a lot — narrow it
with project_id, or switch to list_work_packages when you want structured filters
(assignee, due date, version) rather than text. Attachment-content matching in 'fulltext'
mode depends on instance database configuration and is reported honestly in notes.
For structured filtering use list_work_packages; for one work package's full detail
(description, custom fields, children) use get_work_package.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'quick' (default) matches subject, id, project name and type/status names — this is what the OpenProject header search runs and the right choice for 'find the ticket called X'. 'fulltext' additionally matches description text, comments and searchable custom fields; use it for 'which ticket mentions Y'. | quick |
| page | No | 1-based page number. | |
| query | Yes | Free text to look for. In 'quick' mode a bare number also matches a work package id, so '1234' finds #1234. | |
| page_size | No | Results per page (max 100). | |
| project_id | No | Restrict the search to one project: numeric id or the project identifier (the slug in the OpenProject URL). Both come from list_projects. Omit to search every project the user can see. | |
| status_scope | No | Which statuses to search. Defaults to 'all' because finding closed items is usually the point of a search; pass 'open' to hide finished work. An explicit status filter is always sent, so the server's implicit open-only default never applies. | all |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |