API: Queries

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.
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.

  {
    "_type": "DueDateQueryFilter",
    "name": "Finish date",
    "values": [
      "1"
    ],
    "_links": {
      "filter": {
        "href": "/api/v3/queries/filters/dueDate",
        "title": "Finish date"
      },
      "operator": {
        "href": "/api/v3/queries/operators/<t+",
        "title": "in less than"
      }
      "schema": {
        "href": "/api/v3/queries/filter_instance_schemas/dueDate"
      }
    }
  }

If the values are nonprimitive (e.g. User, Project), they will be listed as objects and the QueryFilterInstance will have a values link.

  {
    "_type": "AssigneeQueryFilter",
    "name": "Assignee",
    "_links": {
      "filter": {
        "href": "/api/v3/queries/filters/assignee",
        "title": "Assignee"
      },
      "operator": {
        "href": "/api/v3/queries/operators/=",
        "title": "is"
      },
      "schema": {
        "href": "/api/v3/queries/filter_instance_schemas/assignee"
      },
      "values": [
        {
          "href": "/api/v3/users/1",
          "title": "OpenProject Admin"
        }
      ]
    }
  }

Methods

View default query for project

Same as viewing an existing, persisted Query in its response, this resource returns an unpersisted query and by that allows to get the default query configuration. The client may also provide additional parameters which will modify the default query. The query will already be scoped for the project.

id
integer

required path

Id of the project the default query is requested for

Example:
1

filters
string

optional query

JSON specifying filter conditions. The filters provided as parameters are not applied to the query but are instead used to override the query’s persisted filters. All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array ([]).

Default:
[{ "status_id": { "operator": "o", "values": null }}]

Example:
[{ "assignee": { "operator": "=", "values": ["1", "5"] }" }]

offset
integer

optional query

Page number inside the queries’ result collection of work packages.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page for the queries’ result collection of work packages.

Example:
25

sortBy
string

optional query

JSON specifying sort criteria. The sort criteria is applied to the query’s result collection of work packages overriding the query’s persisted sort criteria.

Default:
[["id", "asc"]]

Example:
[["status", "asc"]]

groupBy
string

optional query

The column to group by. The grouping criteria is applied to the to the query’s result collection of work packages overriding the query’s persisted group criteria.

Example:
status

showSums
boolean

optional query

Indicates whether properties should be summed up if they support it. The showSums parameter is applied to the to the query’s result collection of work packages overriding the query’s persisted sums property.

Default:
false

Example:
true

timestamps
string

optional query

Indicates the timestamps to filter by when showing changed attributes on work packages. Values can be either ISO8601 dates, ISO8601 durations and the following relative date keywords: “oneDayAgo@HH:MM+HH:MM”, “lastWorkingDay@HH:MM+HH:MM”, “oneWeekAgo@HH:MM+HH:MM”, “oneMonthAgo@HH:MM+HH:MM”. The first “HH:MM” part represents the zero paded hours and minutes. The last “+HH:MM” part represents the timezone offset from UTC associated with the time. Values older than 1 day are accepted only with valid Enterprise Token available.

Default:
PT0S

Example:
2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00

timelineVisible
boolean

optional query

Indicates whether the timeline should be shown.

Default:
false

Example:
true

showHierarchies
boolean

optional query

Indicates whether the hierarchy mode should be enabled.

Default:
true

Example:
true

200

OK

{
  "_embedded": {
    "results": {
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "changeSize": {
          "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        },
        "jumpTo": {
          "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "self": {
          "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        }
      },
      "_type": "WorkPackageCollection",
      "count": 30,
      "offset": 1,
      "pageSize": 2,
      "total": 234
    }
  },
  "_links": {
    "columns": [
      {
        "href": "/api/v3/queries/columns/id",
        "title": "ID"
      },
      {
        "href": "/api/v3/queries/columns/subject",
        "title": "Subject"
      },
      {
        "href": "/api/v3/queries/columns/type",
        "title": "Type"
      },
      {
        "href": "/api/v3/queries/columns/status",
        "title": "Status"
      },
      {
        "href": "/api/v3/queries/columns/priority",
        "title": "Priority"
      },
      {
        "href": "/api/v3/queries/columns/assignee",
        "title": "Assignee"
      },
      {
        "href": "/api/v3/queries/columns/updated_at",
        "title": "Updated on"
      }
    ],
    "groupBy": {
      "href": null,
      "title": null
    },
    "project": {
      "href": "/api/v3/projects/42",
      "title": "Lorem ipsum project"
    },
    "results": {
      "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "self": {
      "href": "/api/v3/projects/42/queries/default",
      "title": "Default"
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    }
  },
  "_type": "Query",
  "filters": [
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      },
      "_type": "StatusQueryFilter",
      "name": "Status"
    }
  ],
  "name": "default",
  "public": false,
  "showHierarchies": true,
  "starred": false,
  "sums": false,
  "timelineVisible": false,
  "timelineZoomLevel": "days"
}
Default_Query_for_ProjectModel
{
  "type": "object",
  "example": {
    "_type": "Query",
    "name": "default",
    "filters": [
      {
        "_type": "StatusQueryFilter",
        "name": "Status",
        "_links": {
          "filter": {
            "href": "/api/v3/queries/filters/status",
            "title": "Status"
          },
          "operator": {
            "href": "/api/v3/queries/operators/o",
            "title": "open"
          },
          "schema": {
            "href": "/api/v3/queries/filter_instance_schemas/status"
          },
          "values": [

          ]
        }
      }
    ],
    "public": false,
    "sums": false,
    "timelineVisible": false,
    "timelineZoomLevel": "days",
    "showHierarchies": true,
    "starred": false,
    "_embedded": {
      "results": {
        "_type": "WorkPackageCollection",
        "total": 234,
        "count": 30,
        "pageSize": 2,
        "offset": 1,
        "_embedded": {
          "elements": [
            "<--- shortened for brevity --->"
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
          },
          "jumpTo": {
            "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "changeSize": {
            "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "createWorkPackage": {
            "href": "/api/v3/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/work_packages",
            "method": "post"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/projects/42/queries/default",
        "title": "Default"
      },
      "results": {
        "href": "/api/v3/projects/42/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
      },
      "columns": [
        {
          "href": "/api/v3/queries/columns/id",
          "title": "ID"
        },
        {
          "href": "/api/v3/queries/columns/subject",
          "title": "Subject"
        },
        {
          "href": "/api/v3/queries/columns/type",
          "title": "Type"
        },
        {
          "href": "/api/v3/queries/columns/status",
          "title": "Status"
        },
        {
          "href": "/api/v3/queries/columns/priority",
          "title": "Priority"
        },
        {
          "href": "/api/v3/queries/columns/assignee",
          "title": "Assignee"
        },
        {
          "href": "/api/v3/queries/columns/updated_at",
          "title": "Updated on"
        }
      ],
      "groupBy": {
        "href": null,
        "title": null
      },
      "sortBy": [
        {
          "href": "/api/v3/queries/sort_bys/parent-desc",
          "title": "Parent (Descending)"
        }
      ],
      "user": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin"
      },
      "project": {
        "href": "/api/v3/projects/42",
        "title": "Lorem ipsum project"
      }
    }
  }
}

403

Returned if the client does not have sufficient permissions to see the default query.

Required permission: view work packages in the project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the client does not have sufficient permissions to see the project.

Required permission: any permission in the project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View schema for project queries

Retrieve the schema for project queries.

id
integer

required path

Project id

Example:
1

200

OK

{
  "_dependencies": [

  ],
  "_embedded": {
    "filtersSchemas": {
      "_embedded": {
        "elements": [
          {
            "_dependencies": [
              {
                "_type": "SchemaDependency",
                "dependencies": {
                  "/api/v3/queries/operators/!": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  },
                  "/api/v3/queries/operators/!*": {
                  },
                  "/api/v3/queries/operators/*": {
                  },
                  "/api/v3/queries/operators/=": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  }
                },
                "on": "operator"
              }
            ],
            "_links": {
              "filter": {
                "href": "/api/v3/queries/filters/assignee",
                "title": "Assignee"
              },
              "self": {
                "href": "/api/v3/queries/filter_instance_schemas/assignee"
              }
            },
            "_type": "QueryFilterInstanceSchema",
            "filter": {
              "_links": {
              },
              "hasDefault": false,
              "name": "Filter",
              "required": true,
              "type": "QueryFilter",
              "writable": true
            },
            "name": {
              "hasDefault": true,
              "name": "Name",
              "required": true,
              "type": "String",
              "writable": false
            }
          },
          {
            "_dependencies": [
              {
                "_type": "SchemaDependency",
                "dependencies": {
                  "/api/v3/queries/operators/!": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  },
                  "/api/v3/queries/operators/=": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  }
                },
                "on": "operator"
              }
            ],
            "_links": {
              "filter": {
                "href": "/api/v3/queries/filters/author",
                "title": "Author"
              },
              "self": {
                "href": "/api/v3/queries/filter_instance_schemas/author"
              }
            },
            "_type": "QueryFilterInstanceSchema",
            "filter": {
              "_links": {
              },
              "hasDefault": false,
              "name": "Filter",
              "required": true,
              "type": "QueryFilter",
              "writable": true
            },
            "name": {
              "hasDefault": true,
              "name": "Name",
              "required": true,
              "type": "String",
              "writable": false
            }
          }
        ]
      },
      "_links": {
        "self": {
          "href": "/api/v3/queries/filter_instance_schemas"
        }
      },
      "_type": "Collection",
      "count": 20,
      "total": 20
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/queries/schema"
    }
  },
  "_type": "Schema",
  "columns": {
    "_links": {
    },
    "hasDefault": true,
    "location": "_links",
    "name": "Columns",
    "required": false,
    "type": "[]QueryColumn",
    "writable": true
  },
  "createdAt": {
    "hasDefault": false,
    "name": "Created on",
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "filters": {
    "_links": {
      "allowedValuesSchemas": {
        "href": "/api/v3/queries/filter_instance_schemas"
      }
    },
    "hasDefault": true,
    "location": "_links",
    "name": "Filters",
    "required": false,
    "type": "[]QueryFilterInstance",
    "writable": true
  },
  "groupBy": {
    "_links": {
    },
    "hasDefault": false,
    "name": "Group results by",
    "required": false,
    "type": "[]QueryGroupBy",
    "writable": true
  },
  "highlightedAttributes": {
    "hasDefault": true,
    "location": "_links",
    "name": "Highlighted attributes",
    "required": false,
    "type": "[]QueryColumn",
    "writable": true,
    "deprecated": true
  },
  "highlightingMode": {
    "hasDefault": true,
    "name": "Highlighting mode",
    "required": false,
    "type": "String",
    "writable": true,
    "deprecated": true
  },
  "id": {
    "hasDefault": false,
    "name": "ID",
    "required": true,
    "type": "Integer",
    "writable": false
  },
  "name": {
    "hasDefault": false,
    "maxLength": 255,
    "minLength": 1,
    "name": "Name",
    "required": true,
    "type": "String",
    "writable": true
  },
  "project": {
    "_links": {
    },
    "hasDefault": false,
    "location": "_links",
    "name": "Project",
    "required": false,
    "type": "Project",
    "writable": true
  },
  "public": {
    "hasDefault": true,
    "name": "Public",
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "results": {
    "hasDefault": false,
    "name": "Results",
    "required": false,
    "type": "WorkPackageCollection",
    "writable": false
  },
  "showHierarchies": {
    "hasDefault": true,
    "name": "Show hierarchies",
    "required": false,
    "type": "Boolean",
    "writable": true,
    "deprecated": true
  },
  "sortBy": {
    "_links": {
    },
    "hasDefault": true,
    "name": "Sort by",
    "required": false,
    "type": "[]QuerySortBy",
    "writable": true
  },
  "starred": {
    "hasDefault": true,
    "name": "Starred",
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "sums": {
    "hasDefault": true,
    "name": "Sums",
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "timelineLabels": {
    "hasDefault": true,
    "name": "Timeline labels",
    "required": false,
    "type": "QueryTimelineLabels",
    "writable": true,
    "deprecated": true
  },
  "timelineVisible": {
    "hasDefault": true,
    "name": "Timeline visible",
    "required": false,
    "type": "Boolean",
    "writable": true,
    "deprecated": true
  },
  "timelineZoomLevel": {
    "hasDefault": true,
    "name": "Timeline zoom level",
    "required": false,
    "type": "String",
    "writable": true,
    "deprecated": true
  },
  "timestamps": {
    "hasDefault": true,
    "name": "Timestamps",
    "required": false,
    "type": "[]Timestamp",
    "writable": true
  },
  "updatedAt": {
    "hasDefault": false,
    "name": "Updated on",
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "user": {
    "hasDefault": true,
    "name": "User",
    "required": true,
    "type": "User",
    "writable": false
  }
}
Schema_For_Project_QueriesModel
{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_dependencies": [

    ],
    "id": {
      "type": "Integer",
      "name": "ID",
      "required": true,
      "hasDefault": false,
      "writable": false
    },
    "name": {
      "type": "String",
      "name": "Name",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "minLength": 1,
      "maxLength": 255
    },
    "createdAt": {
      "type": "DateTime",
      "name": "Created on",
      "required": true,
      "hasDefault": false,
      "writable": false
    },
    "updatedAt": {
      "type": "DateTime",
      "name": "Updated on",
      "required": true,
      "hasDefault": false,
      "writable": false
    },
    "user": {
      "type": "User",
      "name": "User",
      "required": true,
      "hasDefault": true,
      "writable": false
    },
    "project": {
      "type": "Project",
      "name": "Project",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "_links": {
      }
    },
    "public": {
      "type": "Boolean",
      "name": "Public",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "sums": {
      "type": "Boolean",
      "name": "Sums",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "timelineVisible": {
      "type": "Boolean",
      "name": "Timeline visible",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "timelineZoomLevel": {
      "type": "String",
      "name": "Timeline zoom level",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "showHierarchies": {
      "type": "Boolean",
      "name": "Show hierarchies",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "starred": {
      "type": "Boolean",
      "name": "Starred",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "columns": {
      "type": "[]QueryColumn",
      "name": "Columns",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "_links": {
      }
    },
    "filters": {
      "type": "[]QueryFilterInstance",
      "name": "Filters",
      "required": false,
      "writable": true,
      "hasDefault": true,
      "_links": {
        "allowedValuesSchemas": {
          "href": "/api/v3/projects/42/queries/filter_instance_schemas"
        }
      }
    },
    "groupBy": {
      "type": "[]QueryGroupBy",
      "name": "Group results by",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "_links": {
      }
    },
    "sortBy": {
      "type": "[]QuerySortBy",
      "name": "Sort by",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "_links": {
      }
    },
    "results": {
      "type": "WorkPackageCollection",
      "name": "Results",
      "required": false,
      "hasDefault": false,
      "writable": false
    },
    "_embedded": {
      "filtersSchemas": {
        "_type": "Collection",
        "total": 20,
        "count": 20,
        "_embedded": {
          "elements": [
            {
              "_type": "QueryFilterInstanceSchema",
              "_dependencies": [
                {
                  "_type": "SchemaDependency",
                  "on": "operator",
                  "dependencies": {
                    "/api/v3/queries/operators/=": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    },
                    "/api/v3/queries/operators/!": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    },
                    "/api/v3/queries/operators/!*": {
                    },
                    "/api/v3/queries/operators/*": {
                    }
                  }
                }
              ],
              "name": {
                "type": "String",
                "name": "Name",
                "required": true,
                "hasDefault": true,
                "writable": false
              },
              "filter": {
                "type": "QueryFilter",
                "name": "Filter",
                "required": true,
                "hasDefault": false,
                "writable": true,
                "_links": {
                }
              },
              "_links": {
                "self": {
                  "href": "/api/v3/queries/filter_instance_schemas/assignee"
                },
                "filter": {
                  "href": "/api/v3/queries/filters/assignee",
                  "title": "Assignee"
                }
              }
            },
            {
              "_type": "QueryFilterInstanceSchema",
              "_dependencies": [
                {
                  "_type": "SchemaDependency",
                  "on": "operator",
                  "dependencies": {
                    "/api/v3/queries/operators/=": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    },
                    "/api/v3/queries/operators/!": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    }
                  }
                }
              ],
              "name": {
                "type": "String",
                "name": "Name",
                "required": true,
                "hasDefault": true,
                "writable": false
              },
              "filter": {
                "type": "QueryFilter",
                "name": "Filter",
                "required": true,
                "hasDefault": false,
                "writable": true,
                "_links": {
                }
              },
              "_links": {
                "self": {
                  "href": "/api/v3/queries/filter_instance_schemas/author"
                },
                "filter": {
                  "href": "/api/v3/queries/filters/author",
                  "title": "Author"
                }
              }
            }
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v3/projects/42/queries/filter_instance_schemas"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/projects/42/queries/schema"
      }
    }
  }
}

403

Required permission: view work package in the project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List queries

Returns a collection of queries. The collection can be filtered via query parameters similar to how work packages are filtered. Please note however, that the filters are applied to the queries and not to the work packages the queries in turn might return.

filters
string

optional query

JSON specifying filter conditions. Currently supported filters are:

  • project: filters queries by the project they are assigned to. If the project filter is passed with the !* (not any) operator, global queries are returned.

  • id: filters queries based on their id

  • updated_at: filters queries based on the last time they where updated

Example:
[{ "project_id": { "operator": "!*", "values": null }" }]

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/queries"
    }
  },
  "total": 1,
  "count": 1,
  "_type": "Collection",
  "_embedded": {
    "elements": [
      {
        "_type": "Query",
        "id": 9,
        "name": "fdsfdsfdsf",
        "createdAt": "2015-03-20T12:56:56.413Z",
        "updatedAt": "2015-05-20T18:16:53.392Z",
        "filters": [
          {
            "_type": "StatusQueryFilter",
            "name": "Status",
            "_links": {
              "filter": {
                "href": "/api/v3/queries/filters/status",
                "title": "Status"
              },
              "operator": {
                "href": "/api/v3/queries/operators/o",
                "title": "open"
              },
              "schema": {
                "href": "/api/v3/queries/filter_instance_schemas/status"
              },
              "values": [

              ]
            }
          },
          {
            "_type": "DueDateQueryFilter",
            "name": "Finish date",
            "values": [
              "1"
            ],
            "_links": {
              "filter": {
                "href": "/api/v3/queries/filters/dueDate",
                "title": "Finish date"
              },
              "operator": {
                "href": "/api/v3/queries/operators/<t+",
                "title": "in less than"
              },
              "schema": {
                "href": "/api/v3/queries/filter_instance_schemas/dueDate"
              }
            }
          }
        ],
        "public": false,
        "sums": false,
        "starred": true,
        "projections": [
          {
            "_type": "QueryProjection::Table"
          },
          {
            "_type": "QueryProjection::TeamPlanner",
            "_links": {
              "rows": [
                {
                  "href": "/api/v3/users/1",
                  "title": "Bob Bobbit"
                }
              ]
            }
          },
          {
            "_type": "QueryProjection::Calendar"
          }
        ],
        "_embedded": {
          "results": {
            "_type": "WorkPackageCollection",
            "total": 234,
            "count": 30,
            "pageSize": 30,
            "offset": 1,
            "_embedded": {
              "elements": [
                "<--- shortened for brevity --->"
              ]
            },
            "_links": {
              "self": {
                "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
              },
              "jumpTo": {
                "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
                "templated": true
              },
              "changeSize": {
                "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
                "templated": true
              },
              "createWorkPackage": {
                "href": "/api/v3/work_packages/form",
                "method": "post"
              },
              "createWorkPackageImmediate": {
                "href": "/api/v3/work_packages",
                "method": "post"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "/api/v3/queries/9",
            "title": "fdsfdsfdsf"
          },
          "results": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
          },
          "columns": [
            {
              "href": "/api/v3/queries/columns/id",
              "title": "ID"
            },
            {
              "href": "/api/v3/queries/columns/subject",
              "title": "Subject"
            },
            {
              "href": "/api/v3/queries/columns/type",
              "title": "Type"
            },
            {
              "href": "/api/v3/queries/columns/status",
              "title": "Status"
            },
            {
              "href": "/api/v3/queries/columns/priority",
              "title": "Priority"
            },
            {
              "href": "/api/v3/queries/columns/assignee",
              "title": "Assignee"
            },
            {
              "href": "/api/v3/queries/columns/updated_at",
              "title": "Updated on"
            }
          ],
          "groupBy": {
            "href": null,
            "title": null
          },
          "sortBy": [
            {
              "href": "/api/v3/queries/sort_bys/parent-desc",
              "title": "Parent (Descending)"
            }
          ],
          "user": {
            "href": "/api/v3/users/1",
            "title": "OpenProject Admin"
          },
          "project": {
            "href": "/api/v3/projects/3",
            "title": "copy"
          }
        }
      }
    ]
  }
}
QueriesModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/queries"
      }
    },
    "total": 1,
    "count": 1,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_type": "Query",
          "id": 9,
          "name": "fdsfdsfdsf",
          "createdAt": "2015-03-20T12:56:56.858Z",
          "updatedAt": "2015-05-20T18:16:53.887Z",
          "filters": [
            {
              "_type": "StatusQueryFilter",
              "name": "Status",
              "_links": {
                "filter": {
                  "href": "/api/v3/queries/filters/status",
                  "title": "Status"
                },
                "operator": {
                  "href": "/api/v3/queries/operators/o",
                  "title": "open"
                },
                "schema": {
                  "href": "/api/v3/queries/filter_instance_schemas/status"
                },
                "values": [

                ]
              }
            },
            {
              "_type": "DueDateQueryFilter",
              "name": "Finish date",
              "values": [
                "1"
              ],
              "_links": {
                "filter": {
                  "href": "/api/v3/queries/filters/dueDate",
                  "title": "Finish date"
                },
                "operator": {
                  "href": "/api/v3/queries/operators/<t+",
                  "title": "in less than"
                },
                "schema": {
                  "href": "/api/v3/queries/filter_instance_schemas/dueDate"
                }
              }
            }
          ],
          "public": false,
          "sums": false,
          "starred": true,
          "projections": [
            {
              "_type": "Query::TableProjection"
            },
            {
              "_type": "Query::TeamPlannerProjection",
              "_links": {
                "rows": [
                  {
                    "href": "/api/v3/users/1",
                    "title": "Bob Bobbit"
                  }
                ]
              }
            },
            {
              "_type": "Query::CalendarProjection"
            }
          ],
          "_embedded": {
            "results": {
              "_type": "WorkPackageCollection",
              "total": 234,
              "count": 30,
              "pageSize": 30,
              "offset": 1,
              "_embedded": {
                "elements": [
                  "<--- shortened for brevity --->"
                ]
              },
              "_links": {
                "self": {
                  "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
                },
                "jumpTo": {
                  "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
                  "templated": true
                },
                "changeSize": {
                  "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
                  "templated": true
                },
                "createWorkPackage": {
                  "href": "/api/v3/work_packages/form",
                  "method": "post"
                },
                "createWorkPackageImmediate": {
                  "href": "/api/v3/work_packages",
                  "method": "post"
                }
              }
            }
          },
          "_links": {
            "self": {
              "href": "/api/v3/queries/9",
              "title": "fdsfdsfdsf"
            },
            "results": {
              "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
            },
            "columns": [
              {
                "href": "/api/v3/queries/columns/id",
                "title": "ID"
              },
              {
                "href": "/api/v3/queries/columns/subject",
                "title": "Subject"
              },
              {
                "href": "/api/v3/queries/columns/type",
                "title": "Type"
              },
              {
                "href": "/api/v3/queries/columns/status",
                "title": "Status"
              },
              {
                "href": "/api/v3/queries/columns/priority",
                "title": "Priority"
              },
              {
                "href": "/api/v3/queries/columns/assignee",
                "title": "Assignee"
              },
              {
                "href": "/api/v3/queries/columns/updated_at",
                "title": "Updated on"
              }
            ],
            "groupBy": {
              "href": null,
              "title": null
            },
            "sortBy": [
              {
                "href": "/api/v3/queries/sort_bys/parent-desc",
                "title": "Parent (Descending)"
              }
            ],
            "user": {
              "href": "/api/v3/users/1",
              "title": "OpenProject Admin"
            },
            "project": {
              "href": "/api/v3/projects/3",
              "title": "copy"
            }
          }
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions to see queries.

Required permission: view work packages or manage public queries in any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to see the queries."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create query

When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body. The required fields of a Query can be found in its schema, which is embedded in the respective form. Note that it is only allowed to provide properties or links supporting the write operation.

No parameters
{
  "name": "New query name"
}
{
  "name": {
    "type": "string",
    "description": "Query name."
  }
}

201

Created

{
  "_type": "Query",
  "id": 9,
  "name": "abcdefg",
  "createdAt": "2015-03-20T12:56:56.235Z",
  "updatedAt": "2015-05-20T18:16:53.976Z",
  "filters": [
    {
      "_type": "StatusQueryFilter",
      "name": "Status",
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      }
    },
    {
      "_type": "DueDateQueryFilter",
      "name": "Finish date",
      "values": [
        "1"
      ],
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/dueDate",
          "title": "Finish date"
        },
        "operator": {
          "href": "/api/v3/queries/operators/<t+",
          "title": "in less than"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/dueDate"
        }
      }
    }
  ],
  "public": false,
  "sums": false,
  "starred": false,
  "hidden": false,
  "timestamps": [
    "PT0S"
  ],
  "projections": [
    {
      "_type": "QueryProjection::Table",
      "showHierarchies": true,
      "_links": {
        "columns": [
          {
            "href": "/api/v3/queries/columns/id",
            "title": "ID"
          },
          {
            "href": "/api/v3/queries/columns/subject",
            "title": "Subject"
          },
          {
            "href": "/api/v3/queries/columns/type",
            "title": "Type"
          },
          {
            "href": "/api/v3/queries/columns/status",
            "title": "Status"
          },
          {
            "href": "/api/v3/queries/columns/priority",
            "title": "Priority"
          },
          {
            "href": "/api/v3/queries/columns/assignee",
            "title": "Assignee"
          },
          {
            "href": "/api/v3/queries/columns/updated_at",
            "title": "Updated on"
          }
        ],
        "highlightedAttributes": [

        ]
      }
    },
    {
      "_type": "QueryProjection::Gantt",
      "labels": {
      },
      "zoomLevel": "auto",
      "_links": {
        "highlightedAttributes": [

        ]
      }
    },
    {
      "_type": "QueryProjection::TeamPlanner",
      "_links": {
        "rows": [
          {
            "href": "/api/v3/users/1",
            "title": "Alan Touring"
          },
          {
            "href": "/api/v3/users/5",
            "title": "John von Neumann"
          }
        ]
      }
    },
    {
      "_type": "QueryProjection::Calendar"
    }
  ],
  "_embedded": {
    "results": {
      "_type": "WorkPackageCollection",
      "total": 234,
      "count": 30,
      "pageSize": 30,
      "offset": 1,
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "self": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        },
        "jumpTo": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "changeSize": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        }
      }
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/queries/9",
      "title": "abcdefg"
    },
    "results": {
      "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "groupBy": {
      "href": null,
      "title": null
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    },
    "project": {
      "href": "/api/v3/projects/3",
      "title": "copy"
    }
  }
}
QueryModel
{
  "type": "object",
  "required": [
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Query id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Query name",
      "readOnly": true
    },
    "filters": {
      "type": "array",
      "description": "A set of QueryFilters which will be applied to the work packages to determine the resulting work packages",
      "readOnly": false,
      "items": {
        "$ref": "#/components/schemas/Query_Filter_Instance_SchemaModel"
      }
    },
    "sums": {
      "type": "boolean",
      "description": "Should sums (of supported properties) be shown?",
      "readOnly": true
    },
    "timelineVisible": {
      "type": "boolean",
      "description": "Should the timeline mode be shown?",
      "readOnly": true,
      "deprecated": true
    },
    "timelineLabels": {
      "type": "array",
      "description": "Which labels are shown in the timeline, empty when default",
      "readOnly": true,
      "deprecated": true,
      "items": {
        "type": "string"
      }
    },
    "timelineZoomLevel": {
      "type": "string",
      "description": "Which zoom level should the timeline be rendered in?",
      "readOnly": true,
      "deprecated": true
    },
    "timestamps": {
      "type": "array",
      "description": "Timestamps to filter by when showing changed attributes on work packages.",
      "readOnly": false
    },
    "highlightingMode": {
      "type": "string",
      "description": "Which highlighting mode should the table have?",
      "readOnly": true,
      "deprecated": true
    },
    "showHierarchies": {
      "type": "boolean",
      "description": "Should the hierarchy mode be enabled?",
      "readOnly": true,
      "deprecated": true
    },
    "hidden": {
      "type": "boolean",
      "description": "Should the query be hidden from the query list?",
      "readOnly": true,
      "deprecated": true
    },
    "public": {
      "type": "boolean",
      "description": "Can users besides the owner see the query?",
      "readOnly": true
    },
    "starred": {
      "type": "boolean",
      "description": "Should the query be highlighted to the user?",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the query",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "properties": {
        "star": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Elevates the query to the status of 'starred'\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries; Only present if query is not yet starred",
              "readOnly": true
            }
          ]
        },
        "unstar": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Removes the 'starred' status\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries; Only present if query is starred",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Use the Form based process to verify the query before persisting\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Persist the query without using a Form based process for guidance\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries;",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

  • the client provides a link to an invalid resource (ResourceTypeMismatch), e.g. a user, project or operator not found

{
  "_embedded": {
    "details": {
      "attribute": "project"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Project not found"
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Available projects for query

Gets a list of projects that are available as projects a query can be assigned to.

No parameters

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "categories": {
            "href": "/api/v3/projects/6/categories"
          },
          "createWorkPackage": {
            "href": "/api/v3/projects/6/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/projects/6/work_packages",
            "method": "post"
          },
          "self": {
            "href": "/api/v3/projects/6",
            "title": "A project"
          },
          "versions": {
            "href": "/api/v3/projects/6/versions"
          }
        },
        "_type": "Project",
        "createdAt": "2015-07-06T13:28:14+00:00",
        "description": "Eveniet molestias omnis quis aut qui eum adipisci.",
        "id": 6,
        "identifier": "a_project",
        "name": "A project",
        "type": "Customer Project",
        "updatedAt": "2015-10-01T09:55:02+00:00"
      },
      {
        "_links": {
          "categories": {
            "href": "/api/v3/projects/14/categories"
          },
          "createWorkPackage": {
            "href": "/api/v3/projects/14/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/projects/14/work_packages",
            "method": "post"
          },
          "self": {
            "href": "/api/v3/projects/14",
            "title": "Another project"
          },
          "versions": {
            "href": "/api/v3/projects/14/versions"
          }
        },
        "_type": "Project",
        "createdAt": "2016-02-29T12:50:20+00:00",
        "description": "",
        "id": 14,
        "identifier": "another_project",
        "name": "Another project",
        "type": null,
        "updatedAt": "2016-02-29T12:50:20+00:00"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/queries/available_projects"
    }
  },
  "_type": "Collection",
  "count": 2,
  "total": 2
}
Available_projects_for_queryModel
{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/queries/available_projects"
      }
    },
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_embedded": {
      "elements": [
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/6",
              "title": "A project"
            },
            "createWorkPackage": {
              "href": "/api/v3/projects/6/work_packages/form",
              "method": "post"
            },
            "createWorkPackageImmediate": {
              "href": "/api/v3/projects/6/work_packages",
              "method": "post"
            },
            "categories": {
              "href": "/api/v3/projects/6/categories"
            },
            "versions": {
              "href": "/api/v3/projects/6/versions"
            }
          },
          "id": 6,
          "identifier": "a_project",
          "name": "A project",
          "description": "Eveniet molestias omnis quis aut qui eum adipisci.",
          "createdAt": "2015-07-06T13:28:14+00:00",
          "updatedAt": "2015-10-01T09:55:02+00:00",
          "type": "Customer Project"
        },
        {
          "_type": "Project",
          "_links": {
            "self": {
              "href": "/api/v3/projects/14",
              "title": "Another project"
            },
            "createWorkPackage": {
              "href": "/api/v3/projects/14/work_packages/form",
              "method": "post"
            },
            "createWorkPackageImmediate": {
              "href": "/api/v3/projects/14/work_packages",
              "method": "post"
            },
            "categories": {
              "href": "/api/v3/projects/14/categories"
            },
            "versions": {
              "href": "/api/v3/projects/14/versions"
            }
          },
          "id": 14,
          "identifier": "another_project",
          "name": "Another project",
          "description": "",
          "createdAt": "2016-02-29T12:50:20+00:00",
          "updatedAt": "2016-02-29T12:50:20+00:00",
          "type": null
        }
      ]
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: view work packages

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View default query

Same as viewing an existing, persisted Query in its response, this resource returns an unpersisted query and by that allows to get the default query configuration. The client may also provide additional parameters which will modify the default query.

filters
string

optional query

JSON specifying filter conditions. The filters provided as parameters are not applied to the query but are instead used to override the query’s persisted filters. All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array ([]).

Default:
[{ "status_id": { "operator": "o", "values": null }}]

Example:
[{ "assignee": { "operator": "=", "values": ["1", "5"] }" }]

offset
integer

optional query

Page number inside the queries’ result collection of work packages.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page for the queries’ result collection of work packages.

Example:
25

sortBy
string

optional query

JSON specifying sort criteria. The sort criteria is applied to the query’s result collection of work packages overriding the query’s persisted sort criteria.

Default:
[["id", "asc"]]

Example:
[["status", "asc"]]

groupBy
string

optional query

The column to group by. The grouping criteria is applied to the to the query’s result collection of work packages overriding the query’s persisted group criteria.

Example:
status

showSums
boolean

optional query

Indicates whether properties should be summed up if they support it. The showSums parameter is applied to the to the query’s result collection of work packages overriding the query’s persisted sums property.

Default:
false

Example:
true

timestamps
string

optional query

Indicates the timestamps to filter by when showing changed attributes on work packages. Values can be either ISO8601 dates, ISO8601 durations and the following relative date keywords: “oneDayAgo@HH:MM+HH:MM”, “lastWorkingDay@HH:MM+HH:MM”, “oneWeekAgo@HH:MM+HH:MM”, “oneMonthAgo@HH:MM+HH:MM”. The first “HH:MM” part represents the zero paded hours and minutes. The last “+HH:MM” part represents the timezone offset from UTC associated with the time, the offset can be positive or negative e.g.“oneDayAgo@01:00+01:00”, “oneDayAgo@01:00-01:00”. Values older than 1 day are accepted only with valid Enterprise Token available.

Default:
PT0S

Example:
2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00

timelineVisible
boolean

optional query

Indicates whether the timeline should be shown.

Default:
false

Example:
true

timelineZoomLevel
string

optional query

Indicates in what zoom level the timeline should be shown. Valid values are days, weeks, months, quarters, and years.

Default:
days

Example:
days

showHierarchies
boolean

optional query

Indicates whether the hierarchy mode should be enabled.

Default:
true

Example:
true

200

OK

{
  "_embedded": {
    "results": {
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "changeSize": {
          "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        },
        "jumpTo": {
          "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "self": {
          "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        }
      },
      "_type": "WorkPackageCollection",
      "count": 30,
      "offset": 1,
      "pageSize": 2,
      "total": 234
    }
  },
  "_links": {
    "columns": [
      {
        "href": "/api/v3/queries/columns/id",
        "title": "ID"
      },
      {
        "href": "/api/v3/queries/columns/subject",
        "title": "Subject"
      },
      {
        "href": "/api/v3/queries/columns/type",
        "title": "Type"
      },
      {
        "href": "/api/v3/queries/columns/status",
        "title": "Status"
      },
      {
        "href": "/api/v3/queries/columns/priority",
        "title": "Priority"
      },
      {
        "href": "/api/v3/queries/columns/assignee",
        "title": "Assignee"
      },
      {
        "href": "/api/v3/queries/columns/updated_at",
        "title": "Updated on"
      }
    ],
    "groupBy": {
      "href": null,
      "title": null
    },
    "highlightedAttributes": [

    ],
    "project": {
      "href": null
    },
    "results": {
      "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "self": {
      "href": "/api/v3/queries/default",
      "title": "Default"
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    }
  },
  "_type": "Query",
  "filters": [
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      },
      "_type": "StatusQueryFilter",
      "name": "Status"
    }
  ],
  "highlightingMode": "inline",
  "name": "default",
  "public": false,
  "showHierarchies": true,
  "starred": false,
  "sums": false,
  "timelineLabels": {
  },
  "timelineVisible": false,
  "timelineZoomLevel": "days"
}
Default_QueryModel
{
  "type": "object",
  "example": {
    "_type": "Query",
    "name": "default",
    "filters": [
      {
        "_type": "StatusQueryFilter",
        "name": "Status",
        "_links": {
          "filter": {
            "href": "/api/v3/queries/filters/status",
            "title": "Status"
          },
          "operator": {
            "href": "/api/v3/queries/operators/o",
            "title": "open"
          },
          "schema": {
            "href": "/api/v3/queries/filter_instance_schemas/status"
          },
          "values": [

          ]
        }
      }
    ],
    "public": false,
    "sums": false,
    "timelineVisible": false,
    "timelineZoomLevel": "days",
    "timelineLabels": {
    },
    "highlightingMode": "inline",
    "timestamps": [
      "P0D"
    ],
    "showHierarchies": true,
    "starred": false,
    "_embedded": {
      "results": {
        "_type": "WorkPackageCollection",
        "total": 234,
        "count": 30,
        "pageSize": 2,
        "offset": 1,
        "_embedded": {
          "elements": [
            "<--- shortened for brevity --->"
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
          },
          "jumpTo": {
            "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "changeSize": {
            "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "createWorkPackage": {
            "href": "/api/v3/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/work_packages",
            "method": "post"
          }
        },
        "highlightedAttributes": [

        ]
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/queries/default",
        "title": "Default"
      },
      "results": {
        "href": "/api/v3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
      },
      "columns": [
        {
          "href": "/api/v3/queries/columns/id",
          "title": "ID"
        },
        {
          "href": "/api/v3/queries/columns/subject",
          "title": "Subject"
        },
        {
          "href": "/api/v3/queries/columns/type",
          "title": "Type"
        },
        {
          "href": "/api/v3/queries/columns/status",
          "title": "Status"
        },
        {
          "href": "/api/v3/queries/columns/priority",
          "title": "Priority"
        },
        {
          "href": "/api/v3/queries/columns/assignee",
          "title": "Assignee"
        },
        {
          "href": "/api/v3/queries/columns/updated_at",
          "title": "Updated on"
        }
      ],
      "highlightedAttributes": [

      ],
      "groupBy": {
        "href": null,
        "title": null
      },
      "sortBy": [
        {
          "href": "/api/v3/queries/sort_bys/parent-desc",
          "title": "Parent (Descending)"
        }
      ],
      "user": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin"
      },
      "project": {
        "href": null
      }
    }
  }
}

403

Returned if the client does not have sufficient permissions to see the default query.

Required permission: view work packages in any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Query create form

No parameters
{
  "name": "New query name"
}
{
  "name": {
    "type": "string",
    "description": "Query name."
  }
}

200

OK

View schema for global queries

Retrieve the schema for global queries, those, that are not assigned to a project.

No parameters

200

OK

{
  "_dependencies": [

  ],
  "_embedded": {
    "filtersSchemas": {
      "_embedded": {
        "elements": [
          {
            "_dependencies": [
              {
                "_type": "SchemaDependency",
                "dependencies": {
                  "/api/v3/queries/operators/!": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  },
                  "/api/v3/queries/operators/!*": {
                  },
                  "/api/v3/queries/operators/*": {
                  },
                  "/api/v3/queries/operators/=": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  }
                },
                "on": "operator"
              }
            ],
            "_links": {
              "filter": {
                "href": "/api/v3/queries/filters/assignee",
                "title": "Assignee"
              },
              "self": {
                "href": "/api/v3/queries/filter_instance_schemas/assignee"
              }
            },
            "_type": "QueryFilterInstanceSchema",
            "filter": {
              "_links": {
              },
              "hasDefault": false,
              "name": "Filter",
              "required": true,
              "type": "QueryFilter",
              "writable": true
            },
            "name": {
              "hasDefault": true,
              "name": "Name",
              "required": true,
              "type": "String",
              "writable": false
            }
          },
          {
            "_dependencies": [
              {
                "_type": "SchemaDependency",
                "dependencies": {
                  "/api/v3/queries/operators/!": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  },
                  "/api/v3/queries/operators/=": {
                    "values": {
                      "_links": {
                      },
                      "hasDefault": false,
                      "name": "Values",
                      "required": true,
                      "type": "[]User",
                      "writable": true
                    }
                  }
                },
                "on": "operator"
              }
            ],
            "_links": {
              "filter": {
                "href": "/api/v3/queries/filters/author",
                "title": "Author"
              },
              "self": {
                "href": "/api/v3/queries/filter_instance_schemas/author"
              }
            },
            "_type": "QueryFilterInstanceSchema",
            "filter": {
              "_links": {
              },
              "hasDefault": false,
              "name": "Filter",
              "required": true,
              "type": "QueryFilter",
              "writable": true
            },
            "name": {
              "hasDefault": true,
              "name": "Name",
              "required": true,
              "type": "String",
              "writable": false
            }
          }
        ]
      },
      "_links": {
        "self": {
          "href": "/api/v3/queries/filter_instance_schemas"
        }
      },
      "_type": "Collection",
      "count": 20,
      "total": 20
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/queries/schema"
    }
  },
  "_type": "Schema",
  "columns": {
    "_links": {
    },
    "hasDefault": true,
    "location": "_links",
    "name": "Columns",
    "required": false,
    "type": "[]QueryColumn",
    "writable": true
  },
  "createdAt": {
    "hasDefault": false,
    "name": "Created on",
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "filters": {
    "_links": {
      "allowedValuesSchemas": {
        "href": "/api/v3/queries/filter_instance_schemas"
      }
    },
    "hasDefault": true,
    "location": "_links",
    "name": "Filters",
    "required": false,
    "type": "[]QueryFilterInstance",
    "writable": true
  },
  "groupBy": {
    "_links": {
    },
    "hasDefault": false,
    "name": "Group results by",
    "required": false,
    "type": "[]QueryGroupBy",
    "writable": true
  },
  "highlightedAttributes": {
    "hasDefault": true,
    "location": "_links",
    "name": "Highlighted attributes",
    "required": false,
    "type": "[]QueryColumn",
    "writable": true,
    "deprecated": true
  },
  "highlightingMode": {
    "hasDefault": true,
    "name": "Highlighting mode",
    "required": false,
    "type": "String",
    "writable": true,
    "deprecated": true
  },
  "id": {
    "hasDefault": false,
    "name": "ID",
    "required": true,
    "type": "Integer",
    "writable": false
  },
  "name": {
    "hasDefault": false,
    "maxLength": 255,
    "minLength": 1,
    "name": "Name",
    "required": true,
    "type": "String",
    "writable": true
  },
  "project": {
    "_links": {
    },
    "hasDefault": false,
    "location": "_links",
    "name": "Project",
    "required": false,
    "type": "Project",
    "writable": true
  },
  "public": {
    "hasDefault": true,
    "name": "Public",
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "results": {
    "hasDefault": false,
    "name": "Results",
    "required": false,
    "type": "WorkPackageCollection",
    "writable": false
  },
  "showHierarchies": {
    "hasDefault": true,
    "name": "Show hierarchies",
    "required": false,
    "type": "Boolean",
    "writable": true,
    "deprecated": true
  },
  "sortBy": {
    "_links": {
    },
    "hasDefault": true,
    "name": "Sort by",
    "required": false,
    "type": "[]QuerySortBy",
    "writable": true
  },
  "starred": {
    "hasDefault": true,
    "name": "Starred",
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "sums": {
    "hasDefault": true,
    "name": "Sums",
    "required": false,
    "type": "Boolean",
    "writable": true
  },
  "timelineLabels": {
    "hasDefault": true,
    "name": "Timeline labels",
    "required": false,
    "type": "QueryTimelineLabels",
    "writable": true,
    "deprecated": true
  },
  "timelineVisible": {
    "hasDefault": true,
    "name": "Timeline visible",
    "required": false,
    "type": "Boolean",
    "writable": true,
    "deprecated": true
  },
  "timelineZoomLevel": {
    "hasDefault": true,
    "name": "Timeline zoom level",
    "required": false,
    "type": "String",
    "writable": true,
    "deprecated": true
  },
  "timestamps": {
    "hasDefault": true,
    "name": "Timestamps",
    "required": false,
    "type": "[]Timestamp",
    "writable": true
  },
  "updatedAt": {
    "hasDefault": false,
    "name": "Updated on",
    "required": true,
    "type": "DateTime",
    "writable": false
  },
  "user": {
    "hasDefault": true,
    "name": "User",
    "required": true,
    "type": "User",
    "writable": false
  }
}
Schema_For_Global_QueriesModel
{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_dependencies": [

    ],
    "id": {
      "type": "Integer",
      "name": "ID",
      "required": true,
      "hasDefault": false,
      "writable": false
    },
    "name": {
      "type": "String",
      "name": "Name",
      "required": true,
      "hasDefault": false,
      "writable": true,
      "minLength": 1,
      "maxLength": 255
    },
    "createdAt": {
      "type": "DateTime",
      "name": "Created on",
      "required": true,
      "hasDefault": false,
      "writable": false
    },
    "updatedAt": {
      "type": "DateTime",
      "name": "Updated on",
      "required": true,
      "hasDefault": false,
      "writable": false
    },
    "user": {
      "type": "User",
      "name": "User",
      "required": true,
      "hasDefault": true,
      "writable": false
    },
    "project": {
      "type": "Project",
      "name": "Project",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "location": "_links",
      "_links": {
      }
    },
    "public": {
      "type": "Boolean",
      "name": "Public",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "sums": {
      "type": "Boolean",
      "name": "Sums",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "timelineVisible": {
      "type": "Boolean",
      "name": "Timeline visible",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "deprecated": true
    },
    "timelineZoomLevel": {
      "type": "String",
      "name": "Timeline zoom level",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "deprecated": true
    },
    "timelineLabels": {
      "type": "QueryTimelineLabels",
      "name": "Timeline labels",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "deprecated": true
    },
    "timestamps": {
      "type": "[]Timestamp",
      "name": "Timestamps",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "highlightingMode": {
      "type": "String",
      "name": "Highlighting mode",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "deprecated": true
    },
    "highlightedAttributes": {
      "type": "[]QueryColumn",
      "name": "Highlighted attributes",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "location": "_links",
      "deprecated": true
    },
    "showHierarchies": {
      "type": "Boolean",
      "name": "Show hierarchies",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "deprecated": true
    },
    "starred": {
      "type": "Boolean",
      "name": "Starred",
      "required": false,
      "hasDefault": true,
      "writable": true
    },
    "columns": {
      "type": "[]QueryColumn",
      "name": "Columns",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "location": "_links",
      "_links": {
      }
    },
    "filters": {
      "type": "[]QueryFilterInstance",
      "name": "Filters",
      "required": false,
      "writable": true,
      "hasDefault": true,
      "location": "_links",
      "_links": {
        "allowedValuesSchemas": {
          "href": "/api/v3/queries/filter_instance_schemas"
        }
      }
    },
    "groupBy": {
      "type": "[]QueryGroupBy",
      "name": "Group results by",
      "required": false,
      "hasDefault": false,
      "writable": true,
      "_links": {
      }
    },
    "sortBy": {
      "type": "[]QuerySortBy",
      "name": "Sort by",
      "required": false,
      "hasDefault": true,
      "writable": true,
      "_links": {
      }
    },
    "results": {
      "type": "WorkPackageCollection",
      "name": "Results",
      "required": false,
      "hasDefault": false,
      "writable": false
    },
    "_embedded": {
      "filtersSchemas": {
        "_type": "Collection",
        "total": 20,
        "count": 20,
        "_embedded": {
          "elements": [
            {
              "_type": "QueryFilterInstanceSchema",
              "_dependencies": [
                {
                  "_type": "SchemaDependency",
                  "on": "operator",
                  "dependencies": {
                    "/api/v3/queries/operators/=": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    },
                    "/api/v3/queries/operators/!": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    },
                    "/api/v3/queries/operators/!*": {
                    },
                    "/api/v3/queries/operators/*": {
                    }
                  }
                }
              ],
              "name": {
                "type": "String",
                "name": "Name",
                "required": true,
                "hasDefault": true,
                "writable": false
              },
              "filter": {
                "type": "QueryFilter",
                "name": "Filter",
                "required": true,
                "hasDefault": false,
                "writable": true,
                "_links": {
                }
              },
              "_links": {
                "self": {
                  "href": "/api/v3/queries/filter_instance_schemas/assignee"
                },
                "filter": {
                  "href": "/api/v3/queries/filters/assignee",
                  "title": "Assignee"
                }
              }
            },
            {
              "_type": "QueryFilterInstanceSchema",
              "_dependencies": [
                {
                  "_type": "SchemaDependency",
                  "on": "operator",
                  "dependencies": {
                    "/api/v3/queries/operators/=": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    },
                    "/api/v3/queries/operators/!": {
                      "values": {
                        "type": "[]User",
                        "name": "Values",
                        "required": true,
                        "hasDefault": false,
                        "writable": true,
                        "_links": {
                        }
                      }
                    }
                  }
                }
              ],
              "name": {
                "type": "String",
                "name": "Name",
                "required": true,
                "hasDefault": true,
                "writable": false
              },
              "filter": {
                "type": "QueryFilter",
                "name": "Filter",
                "required": true,
                "hasDefault": false,
                "writable": true,
                "_links": {
                }
              },
              "_links": {
                "self": {
                  "href": "/api/v3/queries/filter_instance_schemas/author"
                },
                "filter": {
                  "href": "/api/v3/queries/filters/author",
                  "title": "Author"
                }
              }
            }
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v3/queries/filter_instance_schemas"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/queries/schema"
      }
    }
  }
}

403

Required permission: view work package in any project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View query

Retrieve an individual query as identified by the id parameter. Then end point accepts a number of parameters that can be used to override the resources’ persisted parameters.

id
integer

required path

Query id

Example:
1

filters
string

optional query

JSON specifying filter conditions. The filters provided as parameters are not applied to the query but are instead used to override the query’s persisted filters. All filters also accepted by the work packages endpoint are accepted. If no filter is to be applied, the client should send an empty array ([]).

Default:
[{ "status_id": { "operator": "o", "values": null }}]

Example:
[{ "assignee": { "operator": "=", "values": ["1", "5"] }" }]

offset
integer

optional query

Page number inside the queries’ result collection of work packages.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page for the queries’ result collection of work packages.

Example:
25

columns
string

optional query

Selected columns for the table view.

Default:
['type', 'priority']

Example:
[]

sortBy
string

optional query

JSON specifying sort criteria. The sort criteria is applied to the query’s result collection of work packages overriding the query’s persisted sort criteria.

Default:
[["id", "asc"]]

Example:
[["status", "asc"]]

groupBy
string

optional query

The column to group by. The grouping criteria is applied to the to the query’s result collection of work packages overriding the query’s persisted group criteria.

Example:
status

showSums
boolean

optional query

Indicates whether properties should be summed up if they support it. The showSums parameter is applied to the to the query’s result collection of work packages overriding the query’s persisted sums property.

Default:
false

Example:
true

timestamps
string

optional query

Indicates the timestamps to filter by when showing changed attributes on work packages. Values can be either ISO8601 dates, ISO8601 durations and the following relative date keywords: “oneDayAgo@HH:MM+HH:MM”, “lastWorkingDay@HH:MM+HH:MM”, “oneWeekAgo@HH:MM+HH:MM”, “oneMonthAgo@HH:MM+HH:MM”. The first “HH:MM” part represents the zero paded hours and minutes. The last “+HH:MM” part represents the timezone offset from UTC associated with the time, the offset can be positive or negative e.g.“oneDayAgo@01:00+01:00”, “oneDayAgo@01:00-01:00”. Values older than 1 day are accepted only with valid Enterprise Token available.

Default:
PT0S

Example:
2023-01-01,P-1Y,PT0S,lastWorkingDay@12:00

timelineVisible
boolean

optional query

Indicates whether the timeline should be shown.

Default:
false

Example:
true

timelineLabels
string

optional query

Overridden labels in the timeline view

Default:
{}

Example:
{}

highlightingMode
string

optional query

Highlighting mode for the table view.

Default:
inline

Example:
inline

highlightedAttributes
string

optional query

Highlighted attributes mode for the table view when highlightingMode is inline. When set to [] all highlightable attributes will be returned as highlightedAttributes.

Default:
['type', 'priority']

Example:
[]

showHierarchies
boolean

optional query

Indicates whether the hierarchy mode should be enabled.

Default:
true

Example:
true

200

OK

{
  "_type": "Query",
  "id": 9,
  "name": "abcdefg",
  "createdAt": "2015-03-20T12:56:56.235Z",
  "updatedAt": "2015-05-20T18:16:53.976Z",
  "filters": [
    {
      "_type": "StatusQueryFilter",
      "name": "Status",
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      }
    },
    {
      "_type": "DueDateQueryFilter",
      "name": "Finish date",
      "values": [
        "1"
      ],
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/dueDate",
          "title": "Finish date"
        },
        "operator": {
          "href": "/api/v3/queries/operators/<t+",
          "title": "in less than"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/dueDate"
        }
      }
    }
  ],
  "public": false,
  "sums": false,
  "starred": false,
  "hidden": false,
  "timestamps": [
    "PT0S"
  ],
  "projections": [
    {
      "_type": "QueryProjection::Table",
      "showHierarchies": true,
      "_links": {
        "columns": [
          {
            "href": "/api/v3/queries/columns/id",
            "title": "ID"
          },
          {
            "href": "/api/v3/queries/columns/subject",
            "title": "Subject"
          },
          {
            "href": "/api/v3/queries/columns/type",
            "title": "Type"
          },
          {
            "href": "/api/v3/queries/columns/status",
            "title": "Status"
          },
          {
            "href": "/api/v3/queries/columns/priority",
            "title": "Priority"
          },
          {
            "href": "/api/v3/queries/columns/assignee",
            "title": "Assignee"
          },
          {
            "href": "/api/v3/queries/columns/updated_at",
            "title": "Updated on"
          }
        ],
        "highlightedAttributes": [

        ]
      }
    },
    {
      "_type": "QueryProjection::Gantt",
      "labels": {
      },
      "zoomLevel": "auto",
      "_links": {
        "highlightedAttributes": [

        ]
      }
    },
    {
      "_type": "QueryProjection::TeamPlanner",
      "_links": {
        "rows": [
          {
            "href": "/api/v3/users/1",
            "title": "Alan Touring"
          },
          {
            "href": "/api/v3/users/5",
            "title": "John von Neumann"
          }
        ]
      }
    },
    {
      "_type": "QueryProjection::Calendar"
    }
  ],
  "_embedded": {
    "results": {
      "_type": "WorkPackageCollection",
      "total": 234,
      "count": 30,
      "pageSize": 30,
      "offset": 1,
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "self": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        },
        "jumpTo": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "changeSize": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        }
      }
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/queries/9",
      "title": "abcdefg"
    },
    "results": {
      "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "groupBy": {
      "href": null,
      "title": null
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    },
    "project": {
      "href": "/api/v3/projects/3",
      "title": "copy"
    }
  }
}
QueryModel
{
  "type": "object",
  "required": [
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Query id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Query name",
      "readOnly": true
    },
    "filters": {
      "type": "array",
      "description": "A set of QueryFilters which will be applied to the work packages to determine the resulting work packages",
      "readOnly": false,
      "items": {
        "$ref": "#/components/schemas/Query_Filter_Instance_SchemaModel"
      }
    },
    "sums": {
      "type": "boolean",
      "description": "Should sums (of supported properties) be shown?",
      "readOnly": true
    },
    "timelineVisible": {
      "type": "boolean",
      "description": "Should the timeline mode be shown?",
      "readOnly": true,
      "deprecated": true
    },
    "timelineLabels": {
      "type": "array",
      "description": "Which labels are shown in the timeline, empty when default",
      "readOnly": true,
      "deprecated": true,
      "items": {
        "type": "string"
      }
    },
    "timelineZoomLevel": {
      "type": "string",
      "description": "Which zoom level should the timeline be rendered in?",
      "readOnly": true,
      "deprecated": true
    },
    "timestamps": {
      "type": "array",
      "description": "Timestamps to filter by when showing changed attributes on work packages.",
      "readOnly": false
    },
    "highlightingMode": {
      "type": "string",
      "description": "Which highlighting mode should the table have?",
      "readOnly": true,
      "deprecated": true
    },
    "showHierarchies": {
      "type": "boolean",
      "description": "Should the hierarchy mode be enabled?",
      "readOnly": true,
      "deprecated": true
    },
    "hidden": {
      "type": "boolean",
      "description": "Should the query be hidden from the query list?",
      "readOnly": true,
      "deprecated": true
    },
    "public": {
      "type": "boolean",
      "description": "Can users besides the owner see the query?",
      "readOnly": true
    },
    "starred": {
      "type": "boolean",
      "description": "Should the query be highlighted to the user?",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the query",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "properties": {
        "star": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Elevates the query to the status of 'starred'\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries; Only present if query is not yet starred",
              "readOnly": true
            }
          ]
        },
        "unstar": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Removes the 'starred' status\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries; Only present if query is starred",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Use the Form based process to verify the query before persisting\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Persist the query without using a Form based process for guidance\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries;",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

404

Returned if the query does not exist or the client does not have sufficient permissions to see it.

Required condition: query belongs to user or query is public

Required permission: view work package in queries project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified query does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Edit query

When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. Note that it is only allowed to provide properties or links supporting the write operation.

id
integer

required path

Query id

Example:
1

{
  "name": "Updated query name"
}
{
  "name": {
    "type": "string",
    "description": "Query name."
  }
}

200

OK

{
  "_embedded": {
    "highlightedAttributes": [

    ],
    "results": {
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "changeSize": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        },
        "jumpTo": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "self": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        }
      },
      "_type": "WorkPackageCollection",
      "count": 30,
      "offset": 1,
      "pageSize": 2,
      "total": 234
    }
  },
  "_links": {
    "columns": [
      {
        "href": "/api/v3/queries/columns/id",
        "title": "ID"
      },
      {
        "href": "/api/v3/queries/columns/subject",
        "title": "Subject"
      },
      {
        "href": "/api/v3/queries/columns/type",
        "title": "Type"
      },
      {
        "href": "/api/v3/queries/columns/status",
        "title": "Status"
      },
      {
        "href": "/api/v3/queries/columns/priority",
        "title": "Priority"
      },
      {
        "href": "/api/v3/queries/columns/assignee",
        "title": "Assignee"
      },
      {
        "href": "/api/v3/queries/columns/updated_at",
        "title": "Updated on"
      }
    ],
    "groupBy": {
      "href": null,
      "title": null
    },
    "highlightedAttributes": [

    ],
    "project": {
      "href": "/api/v3/projects/3",
      "title": "copy"
    },
    "results": {
      "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "self": {
      "href": "/api/v3/queries/9",
      "title": "fdsfdsfdsf"
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    }
  },
  "_type": "Query",
  "createdAt": "2015-03-20T12:56:56.343Z",
  "filters": [
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      },
      "_type": "StatusQueryFilter",
      "name": "Status"
    },
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/dueDate",
          "title": "Finish date"
        },
        "operator": {
          "href": "/api/v3/queries/operators/<t+",
          "title": "in less than"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/dueDate"
        }
      },
      "_type": "DueDateQueryFilter",
      "name": "Finish date",
      "values": [
        "1"
      ]
    }
  ],
  "id": 9,
  "name": "fdsfdsfdsf",
  "public": false,
  "starred": false,
  "sums": false,
  "updatedAt": "2015-05-20T18:16:53.884Z"
}
QueryModel
{
  "type": "object",
  "required": [
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Query id",
      "readOnly": true,
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "description": "Query name",
      "readOnly": true
    },
    "filters": {
      "type": "array",
      "description": "A set of QueryFilters which will be applied to the work packages to determine the resulting work packages",
      "readOnly": false,
      "items": {
        "$ref": "#/components/schemas/Query_Filter_Instance_SchemaModel"
      }
    },
    "sums": {
      "type": "boolean",
      "description": "Should sums (of supported properties) be shown?",
      "readOnly": true
    },
    "timelineVisible": {
      "type": "boolean",
      "description": "Should the timeline mode be shown?",
      "readOnly": true,
      "deprecated": true
    },
    "timelineLabels": {
      "type": "array",
      "description": "Which labels are shown in the timeline, empty when default",
      "readOnly": true,
      "deprecated": true,
      "items": {
        "type": "string"
      }
    },
    "timelineZoomLevel": {
      "type": "string",
      "description": "Which zoom level should the timeline be rendered in?",
      "readOnly": true,
      "deprecated": true
    },
    "timestamps": {
      "type": "array",
      "description": "Timestamps to filter by when showing changed attributes on work packages.",
      "readOnly": false
    },
    "highlightingMode": {
      "type": "string",
      "description": "Which highlighting mode should the table have?",
      "readOnly": true,
      "deprecated": true
    },
    "showHierarchies": {
      "type": "boolean",
      "description": "Should the hierarchy mode be enabled?",
      "readOnly": true,
      "deprecated": true
    },
    "hidden": {
      "type": "boolean",
      "description": "Should the query be hidden from the query list?",
      "readOnly": true,
      "deprecated": true
    },
    "public": {
      "type": "boolean",
      "description": "Can users besides the owner see the query?",
      "readOnly": true
    },
    "starred": {
      "type": "boolean",
      "description": "Should the query be highlighted to the user?",
      "readOnly": true
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation",
      "readOnly": true
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the query",
      "readOnly": true
    },
    "_links": {
      "type": "object",
      "properties": {
        "star": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Elevates the query to the status of 'starred'\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries; Only present if query is not yet starred",
              "readOnly": true
            }
          ]
        },
        "unstar": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Removes the 'starred' status\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries; Only present if query is starred",
              "readOnly": true
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Use the Form based process to verify the query before persisting\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Persist the query without using a Form based process for guidance\n\n# Conditions\n\n**Permission**: save queries for own queries, manage public queries for public queries;",
              "readOnly": true
            }
          ]
        }
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: edit work package

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to edit the content of the work package."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the query does not exist or the client does not have sufficient permissions to see it.

Required permission: view work packages in the query’s project (unless global)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified query does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

  • the client provides a link to an invalid resource (ResourceTypeMismatch)

{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The name might not be blank."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete query

Delete the query identified by the id parameter

id
integer

required path

Query id

Example:
1

204

No Content

403

Returned if the client does not have sufficient permissions.

Required permission: for own queries none; for public queries: manage public queries

Note that you will only receive this error, if you are at least allowed to see the corresponding query.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the query does not exist or the client does not have sufficient permissions to see it.

Required condition: query belongs to user or query is public

Required permission: view work package in queries project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Query update form

id
integer

required path

Query id

Example:
1

{
  "name": "Updated query name"
}
{
  "name": {
    "type": "string",
    "description": "Query name."
  }
}

200

OK

Star query

id
integer

required path

Query id

Example:
1

200

OK

{
  "_embedded": {
    "results": {
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "changeSize": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        },
        "jumpTo": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "self": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        }
      },
      "_type": "WorkPackageCollection",
      "count": 30,
      "offset": 1,
      "pageSize": 2,
      "total": 234
    }
  },
  "_links": {
    "columns": [
      {
        "href": "/api/v3/queries/columns/id",
        "title": "ID"
      },
      {
        "href": "/api/v3/queries/columns/subject",
        "title": "Subject"
      },
      {
        "href": "/api/v3/queries/columns/type",
        "title": "Type"
      },
      {
        "href": "/api/v3/queries/columns/status",
        "title": "Status"
      },
      {
        "href": "/api/v3/queries/columns/priority",
        "title": "Priority"
      },
      {
        "href": "/api/v3/queries/columns/assignee",
        "title": "Assignee"
      },
      {
        "href": "/api/v3/queries/columns/updated_at",
        "title": "Updated on"
      }
    ],
    "groupBy": {
      "href": null,
      "title": null
    },
    "project": {
      "href": "/api/v3/projects/3",
      "title": "copy"
    },
    "results": {
      "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "self": {
      "href": "/api/v3/queries/9",
      "title": "fdsfdsfdsf"
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    }
  },
  "_type": "Query",
  "createdAt": "2015-03-20T12:56:56.856Z",
  "filters": [
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      },
      "_type": "StatusQueryFilter",
      "name": "Status"
    },
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/dueDate",
          "title": "Finish date"
        },
        "operator": {
          "href": "/api/v3/queries/operators/<t+",
          "title": "in less than"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/dueDate"
        }
      },
      "_type": "DueDateQueryFilter",
      "name": "Finish date",
      "values": [
        "1"
      ]
    }
  ],
  "id": 9,
  "name": "fdsfdsfdsf",
  "public": false,
  "starred": true,
  "sums": false,
  "updatedAt": "2015-05-20T18:16:53.089Z"
}
Star_QueryModel
{
  "type": "object",
  "example": {
    "_type": "Query",
    "id": 9,
    "name": "fdsfdsfdsf",
    "createdAt": "2015-03-20T12:56:56.085Z",
    "updatedAt": "2015-05-20T18:16:53.619Z",
    "filters": [
      {
        "_type": "StatusQueryFilter",
        "name": "Status",
        "_links": {
          "filter": {
            "href": "/api/v3/queries/filters/status",
            "title": "Status"
          },
          "operator": {
            "href": "/api/v3/queries/operators/o",
            "title": "open"
          },
          "schema": {
            "href": "/api/v3/queries/filter_instance_schemas/status"
          },
          "values": [

          ]
        }
      },
      {
        "_type": "DueDateQueryFilter",
        "name": "Finish date",
        "values": [
          "1"
        ],
        "_links": {
          "filter": {
            "href": "/api/v3/queries/filters/dueDate",
            "title": "Finish date"
          },
          "operator": {
            "href": "/api/v3/queries/operators/<t+",
            "title": "in less than"
          },
          "schema": {
            "href": "/api/v3/queries/filter_instance_schemas/dueDate"
          }
        }
      }
    ],
    "public": false,
    "sums": false,
    "starred": true,
    "_embedded": {
      "results": {
        "_type": "WorkPackageCollection",
        "total": 234,
        "count": 30,
        "pageSize": 2,
        "offset": 1,
        "_embedded": {
          "elements": [
            "<--- shortened for brevity --->"
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
          },
          "jumpTo": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "changeSize": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "createWorkPackage": {
            "href": "/api/v3/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/work_packages",
            "method": "post"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/queries/9",
        "title": "fdsfdsfdsf"
      },
      "results": {
        "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
      },
      "columns": [
        {
          "href": "/api/v3/queries/columns/id",
          "title": "ID"
        },
        {
          "href": "/api/v3/queries/columns/subject",
          "title": "Subject"
        },
        {
          "href": "/api/v3/queries/columns/type",
          "title": "Type"
        },
        {
          "href": "/api/v3/queries/columns/status",
          "title": "Status"
        },
        {
          "href": "/api/v3/queries/columns/priority",
          "title": "Priority"
        },
        {
          "href": "/api/v3/queries/columns/assignee",
          "title": "Assignee"
        },
        {
          "href": "/api/v3/queries/columns/updated_at",
          "title": "Updated on"
        }
      ],
      "groupBy": {
        "href": null,
        "title": null
      },
      "sortBy": [
        {
          "href": "/api/v3/queries/sort_bys/parent-desc",
          "title": "Parent (Descending)"
        }
      ],
      "user": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin"
      },
      "project": {
        "href": "/api/v3/projects/3",
        "title": "copy"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: for own queries none; for public queries: manage public queries

Note that you will only receive this error, if you are at least allowed to see the corresponding query.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to star this query."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the query does not exist or the client does not have sufficient permissions to see it.

Required condition: query belongs to user or query is public

Required permission: view work package in queries project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified query does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Unstar query

id
integer

required path

Query id

Example:
1

200

OK

{
  "_embedded": {
    "results": {
      "_embedded": {
        "elements": [
          "<--- shortened for brevity --->"
        ]
      },
      "_links": {
        "changeSize": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "createWorkPackage": {
          "href": "/api/v3/work_packages/form",
          "method": "post"
        },
        "createWorkPackageImmediate": {
          "href": "/api/v3/work_packages",
          "method": "post"
        },
        "jumpTo": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
          "templated": true
        },
        "self": {
          "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
        }
      },
      "_type": "WorkPackageCollection",
      "count": 30,
      "offset": 1,
      "pageSize": 2,
      "total": 234
    }
  },
  "_links": {
    "columns": [
      {
        "href": "/api/v3/queries/columns/id",
        "title": "ID"
      },
      {
        "href": "/api/v3/queries/columns/subject",
        "title": "Subject"
      },
      {
        "href": "/api/v3/queries/columns/type",
        "title": "Type"
      },
      {
        "href": "/api/v3/queries/columns/status",
        "title": "Status"
      },
      {
        "href": "/api/v3/queries/columns/priority",
        "title": "Priority"
      },
      {
        "href": "/api/v3/queries/columns/assignee",
        "title": "Assignee"
      },
      {
        "href": "/api/v3/queries/columns/updated_at",
        "title": "Updated on"
      }
    ],
    "groupBy": {
      "href": null,
      "title": null
    },
    "project": {
      "href": "/api/v3/projects/3",
      "title": "copy"
    },
    "results": {
      "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
    },
    "self": {
      "href": "/api/v3/queries/9",
      "title": "fdsfdsfdsf"
    },
    "sortBy": [
      {
        "href": "/api/v3/queries/sort_bys/parent-desc",
        "title": "Parent (Descending)"
      }
    ],
    "user": {
      "href": "/api/v3/users/1",
      "title": "OpenProject Admin"
    }
  },
  "_type": "Query",
  "createdAt": "2015-03-20T12:56:56.468Z",
  "filters": [
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/status",
          "title": "Status"
        },
        "operator": {
          "href": "/api/v3/queries/operators/o",
          "title": "open"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/status"
        },
        "values": [

        ]
      },
      "_type": "StatusQueryFilter",
      "name": "Status"
    },
    {
      "_links": {
        "filter": {
          "href": "/api/v3/queries/filters/dueDate",
          "title": "Finish date"
        },
        "operator": {
          "href": "/api/v3/queries/operators/<t+",
          "title": "in less than"
        },
        "schema": {
          "href": "/api/v3/queries/filter_instance_schemas/dueDate"
        }
      },
      "_type": "DueDateQueryFilter",
      "name": "Finish date",
      "values": [
        "1"
      ]
    }
  ],
  "id": 9,
  "name": "fdsfdsfdsf",
  "public": false,
  "starred": false,
  "sums": false,
  "updatedAt": "2015-05-20T18:16:53.386Z"
}
Unstar_QueryModel
{
  "type": "object",
  "example": {
    "_type": "Query",
    "id": 9,
    "name": "fdsfdsfdsf",
    "createdAt": "2015-03-20T12:56:56.257Z",
    "updatedAt": "2015-05-20T18:16:53.953Z",
    "filters": [
      {
        "_type": "StatusQueryFilter",
        "name": "Status",
        "_links": {
          "filter": {
            "href": "/api/v3/queries/filters/status",
            "title": "Status"
          },
          "operator": {
            "href": "/api/v3/queries/operators/o",
            "title": "open"
          },
          "schema": {
            "href": "/api/v3/queries/filter_instance_schemas/status"
          },
          "values": [

          ]
        }
      },
      {
        "_type": "DueDateQueryFilter",
        "name": "Finish date",
        "values": [
          "1"
        ],
        "_links": {
          "filter": {
            "href": "/api/v3/queries/filters/dueDate",
            "title": "Finish date"
          },
          "operator": {
            "href": "/api/v3/queries/operators/<t+",
            "title": "in less than"
          },
          "schema": {
            "href": "/api/v3/queries/filter_instance_schemas/dueDate"
          }
        }
      }
    ],
    "public": false,
    "sums": false,
    "starred": false,
    "_embedded": {
      "results": {
        "_type": "WorkPackageCollection",
        "total": 234,
        "count": 30,
        "pageSize": 2,
        "offset": 1,
        "_embedded": {
          "elements": [
            "<--- shortened for brevity --->"
          ]
        },
        "_links": {
          "self": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
          },
          "jumpTo": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=%7Boffset%7D&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "changeSize": {
            "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=%7Bsize%7D&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D",
            "templated": true
          },
          "createWorkPackage": {
            "href": "/api/v3/work_packages/form",
            "method": "post"
          },
          "createWorkPackageImmediate": {
            "href": "/api/v3/work_packages",
            "method": "post"
          }
        }
      }
    },
    "_links": {
      "self": {
        "href": "/api/v3/queries/9",
        "title": "fdsfdsfdsf"
      },
      "results": {
        "href": "/api/v3/projects/3/work_packages?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22o%22%2C%22values%22%3A%5B%5D%7D%7D%2C%7B%22dueDate%22%3A%7B%22operator%22%3A%22%3Ct%2B%22%2C%22values%22%3A%5B%221%22%5D%7D%7D%5D&offset=1&pageSize=2&sortBy=%5B%5B%22parent%22%2C%22desc%22%5D%5D"
      },
      "columns": [
        {
          "href": "/api/v3/queries/columns/id",
          "title": "ID"
        },
        {
          "href": "/api/v3/queries/columns/subject",
          "title": "Subject"
        },
        {
          "href": "/api/v3/queries/columns/type",
          "title": "Type"
        },
        {
          "href": "/api/v3/queries/columns/status",
          "title": "Status"
        },
        {
          "href": "/api/v3/queries/columns/priority",
          "title": "Priority"
        },
        {
          "href": "/api/v3/queries/columns/assignee",
          "title": "Assignee"
        },
        {
          "href": "/api/v3/queries/columns/updated_at",
          "title": "Updated on"
        }
      ],
      "groupBy": {
        "href": null,
        "title": null
      },
      "sortBy": [
        {
          "href": "/api/v3/queries/sort_bys/parent-desc",
          "title": "Parent (Descending)"
        }
      ],
      "user": {
        "href": "/api/v3/users/1",
        "title": "OpenProject Admin"
      },
      "project": {
        "href": "/api/v3/projects/3",
        "title": "copy"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: for own queries none; for public queries: manage public queries

Note that you will only receive this error, if you are at least allowed to see the corresponding query.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to unstar this query."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the query does not exist or the client does not have sufficient permissions to see it.

Required condition: query belongs to user or query is public

Required permission: view work package in queries project

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified query does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}