# OpenProject Queries API **Canonical:** https://apis.io/apis/openproject/openproject-queries-api/ **Provider:** OpenProject — https://apis.io/providers/openproject/ **Base URL:** https://community.openproject.org/api/v3 **Documentation:** https://www.openproject.org/docs/api/ OpenProject Queries API is one of 62 APIs that [OpenProject](https://apis.io/providers/openproject/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include Query. The published artifact set on APIs.io includes an OpenAPI specification and API documentation. A query defines how work packages can be filtered and displayed. Clients can define a query once, store it, and use it later on to load the same set of filters and display options. ## Actions | Link | Description | Condition | |:-------------------:|----------------------------------------------------------------------| --------------------------------------- | | star | Elevates the query to the status of 'starred' | **Permission**: save queries for own queries, manage public queries for public queries; Only present if query is not yet starred | | unstar | Removes the 'starred' status | **Permission**: save queries for own queries, manage public queries for public queries; Only present if query is starred | | update | Use the Form based process to verify the query before persisting | **Permission**: view work packages | | updateImmediately | Persist the query without using a Form based process for guidance | **Permission**: save queries for own queries, manage public queries for public queries; | ## Linked Properties | Property | Description | Type | Constraints | Supported operations | | :--------------------: | ------------------------------------------------------ | --------------------- | ------------------------------------------- | -------------------- | | self | This query | Query | not null | READ | | user | The user that owns this query | User | not null | READ | | project | The project on which this query operates | Project | | READ | | columns | Ordered list of QueryColumns. The columns, when mapped to WorkPackage properties determine which WorkPackage properties to display | []QueryColumn | | READ | | highlightedAttributes | **Only with valid Enterprise Token available:** List of QueryColumns that should get highlighted when `highlightingMode` is set to `inline`. | []QueryColumn | | READ | | sortBy | Ordered list of QuerySortBys. Indicates the WorkPackage property the results will be ordered by as well as the direction | []QuerySortBy | | READ | | groupBy | The WorkPackage property results of this query are grouped by | String | | READ | | results | The list of work packages returned by applying the filters, sorting and grouping defined in the query | WorkPackageCollection | | READ | | schema | This query's schema | Schema | | READ | Please note, that all the properties listed above will also be embedded when individual queries are returned but will not be embedded when a list of queries is returned. Whether the properties are embedded or not may be subject to change in the future. The `columns` and `highlightedAttributes` properties will be moved into `Views::WorkPackagesTable` so it is deprecated to have it listed within the Query directly. ## Local Properties | Property | Description | Type | Constraints | Supported operations | | :--------------: | -------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------- | -------------------- | | id | Query id | Integer | x > 0 | READ | | name | Query name | String | | READ/WRITE | | filters | A set of QueryFilters which will be applied to the work packages to determine the resulting work packages| []QueryFilterInstance | | READ/WRITE | | sums | Should sums (of supported properties) be shown? | Boolean | | READ/WRITE | | timelineVisible | Should the timeline mode be shown? | Boolean | | READ/WRITE | | timelineLabels | Which labels are shown in the timeline, empty when default | QueryTimelineLabels | | READ/WRITE | | timelineZoomLevel| Which zoom level should the timeline be rendered in? | String | days, weeks, months, quarters, years | READ/WRITE | | timestamps | The timestamps to filter by when showing changed attributes on work packages.| []Timestamp | | **Values older than 1 day are accepted only with valid Enterprise Token available.**| READ/WRITE | | highlightingMode | Which highlighting mode should the table have? | String | none, inline, status, priority, type | READ/WRITE | | showHierarchies | Should the hierarchy mode be enabled? | Boolean | | READ/WRITE | | hidden | Should the query be hidden from the query list? | Boolean | | READ/WRITE | | public | Can users besides the owner see the query? | Boolean | | READ/WRITE | | starred | Should the query be highlighted to the user? | Boolean | | READ | | createdAt | Time of creation | DateTime | not null | READ | | updatedAt | Time of the most recent change to the query | DateTime | not null | READ | A query that is not assigned to a project (`"project": null`) is called a global query. Global queries filter work packages regardless of the project they are assigned to. As such, a different set of filters exists for those queries. The `hidden` property is deprecated as it is replaced by the `Views` concept. A query that isn't hidden will have a `View` while a query that is hidden won't. The `timelineVisible`, `timelineLabels`, `timelineZoomLevel`, `highlightingMode` and `showHierarchies` properties will be moved into the more appropriate Views (probably `Views::WorkPackagesTable`) so it is deprecated to have them within the Query directly. ## Query Filter Instance A QueryFilterInstance defines a filtering applied to the list of work packages. As such it contains: * the filter type (`QueryFilter`) used * the operator (`QueryOperator`) used * the list of values The list of values can either consist of a list of links or of a list of strings. If the values are primitive (e.g. Integer, Boolean, Date) they will be displayed as strings and the QueryFilterInstance will have a `values` property. ```json { "_type": "DueDateQueryFilter", "name": "Finish date", "values": [ "1" ], "_links": { "filter": { "href": "/api/v3/queries/filters/dueDate", "title": "Finish date" }, "operator": { "href": "/api/v3/queries/operators/