Save a query
save_queryPersist a filter set as a team-wide OpenProject view, validating filters before saving and returning the view ID for later execution.
Instructions
Save a filter set as a reusable OpenProject view the whole team can open.
Use it when a filter combination is worth keeping — "Overdue in Platform", "My open
bugs" — instead of rebuilding it every session: the saved view shows up in the
OpenProject UI as well, and run_query reproduces it exactly. Prove the filters with
list_work_packages first; whatever works there works here.
The call runs POST /queries/form before committing, so an invalid filter name, an
operator the filter does not support, or a project-scoped filter on a global view comes
back as violations naming the attribute — nothing is saved. Returns the stored
definition: {id, name, project, public, starred, filters (as readable sentences), group_by, sort_by, display_sums, updated_at, notes}. Keep the id: it is what
run_query takes.
Pitfalls. Filter values are ids, not names — 'Grace Hopper' is not a value, 12 is.
star=true is a second request after the query exists; if it fails the query is still
saved and notes says so, so never re-save on a starring failure. If OpenProject keeps
fewer filters than were sent, notes says that too — read filters rather than
assuming the view matches the request. Custom-field filters (customField12) are sent
as plain values because a list-typed one cannot be told apart from a text one without
asking the instance; if such a filter makes the call fail, nothing was saved — save that
view in the UI. Editing and deleting saved views is deliberately not offered here:
change or remove them in the OpenProject UI.
Cross-references: list_queries lists what already exists (and gives ids);
run_query(query_id=...) runs this view; list_work_packages is the ad-hoc equivalent
and the place to validate filters first; list_projects supplies project_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name the view is saved under, e.g. 'Overdue in Platform'. Names are not unique upstream, so a second save with the same name creates a second view. | |
| star | No | Also star (favorite) the view for the authenticated user, so it appears in their sidebar. Done as a second call after the query exists; if it fails the query is still saved and 'notes' says so. | |
| public | No | true shares the view with everyone who can see the project; false (default) keeps it private to the authenticated user. Sharing usually needs the 'manage public queries' permission. | |
| filters | Yes | The filters to store, in the same shape run_query's override_filters and list_work_packages' raw_filters take — e.g. [{'name': 'status', 'operator': 'o', 'values': []}, {'name': 'assignee', 'operator': '=', 'values': ['12']}]. Values are ids (or 'me'), not display names. Pass [] deliberately for a view that filters nothing: unlike a listing, a stored query with no filters shows every status. | |
| sort_by | No | Stored sort order, e.g. [['due_date', 'asc'], ['id', 'desc']]. Keys are the snake_case work-package columns list_work_packages sorts by; unknown keys are rejected locally with the allowed set listed. Omit for the default. | |
| group_by | No | Column to group the results by, e.g. 'status', 'assignee', 'type' or 'version'. Grouping is what makes run_query return 'groups' with per-group counts. Omit for a flat list. | |
| project_id | No | Numeric project id the view belongs to, from list_projects. Omit for a global (cross-project) view — but project-scoped filters such as version, category or subprojectId are then rejected. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Query id — pass it to run_query as query_id. | |
| name | No | Query name as its author saved it. | |
| notes | No | What happened beyond the create itself: a failed star, filters OpenProject did not keep. Empty when everything landed as asked. | |
| public | No | True when shared with everyone who can see the project; false when private to its owner. | |
| filters | No | The stored filters as readable sentences, e.g. 'Status open' or 'Assignee is (OR) Grace Hopper'. Empty when the query filters nothing. | |
| project | No | Owning project, or null for a global (cross-project) query. | |
| sort_by | No | Stored sort order, e.g. ['Finish date asc']. | |
| starred | No | True when the current user starred (favorited) it. | |
| group_by | No | Column the results are grouped by, when the query groups. | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| display_sums | No | True when the query asks for totals; then the result 'sums' is populated. |