openproject/docs/api/apiv3/paths/query.yml

# /api/v3/queries/{id}
---
delete:
  parameters:
  - description: Query id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '204':
      description: No Content
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
      description: |-
        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.*
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
      description: |-
        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
      headers: {}
  tags:
  - Queries
  description: Delete the query identified by the id parameter
  operationId: Delete_query
  summary: Delete query
get:
  parameters:
  - description: Query id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  - description: |-
      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 (`[]`).
    example: '[{ "assignee": { "operator": "=", "values": ["1", "5"] }" }]'
    in: query
    name: filters
    required: false
    schema:
      default: '[{ "status_id": { "operator": "o", "values": null }}]'
      type: string
  - description: Page number inside the queries' result collection of work packages.
    example: '25'
    in: query
    name: offset
    required: false
    schema:
      default: 1
      type: integer
  - description: Number of elements to display per page for the queries' result collection
      of work packages.
    example: '25'
    in: query
    name: pageSize
    required: false
    schema:
      type: integer
  - description: Selected columns for the table view.
    example: "[]"
    in: query
    name: columns
    required: false
    schema:
      default: "['type', 'priority']"
      type: string
  - description: 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.
    example: '[["status", "asc"]]'
    in: query
    name: sortBy
    required: false
    schema:
      default: '["id", "asc"]'
      type: string
  - description: 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
    in: query
    name: groupBy
    required: false
    schema:
      type: string
  - description: 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.
    example: 'true'
    in: query
    name: showSums
    required: false
    schema:
      default: 'false'
      type: boolean
  - description: Indicates whether the timeline should be shown.
    example: 'true'
    in: query
    name: timelineVisible
    required: false
    schema:
      default: 'false'
      type: boolean
  - description: Overridden labels in the timeline view
    example: "{}"
    in: query
    name: timelineLabels
    required: false
    schema:
      default: "{}"
      type: string
  - description: Highlighting mode for the table view.
    example: inline
    in: query
    name: highlightingMode
    required: false
    schema:
      default: inline
      type: string
  - description: Highlighted attributes mode for the table view when `highlightingMode`
      is `inline`. When set to `[]` all highlightable attributes will be returned
      as `highlightedAttributes`.
    example: "[]"
    in: query
    name: highlightedAttributes
    required: false
    schema:
      default: "['type', 'priority']"
      type: string
  - description: Indicates whether the hierarchy mode should be enabled.
    example: 'true'
    in: query
    name: showHierarchies
    required: false
    schema:
      default: 'true'
      type: boolean
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _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: 
                    title: 
                  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:56Z'
                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:53Z'
          schema:
            "$ref": "../components/schemas/query_model.yml"
      description: OK
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified query does not exist.
      description: |-
        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
      headers: {}
  tags:
  - Queries
  description: 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.
  operationId: View_query
  summary: View query
patch:
  parameters:
  - description: Query id
    example: '1'
    in: path
    name: id
    required: true
    schema:
      type: integer
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _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: 
                    title: 
                  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:56Z'
                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:53Z'
          schema:
            "$ref": "../components/schemas/query_model.yml"
      description: OK
      headers: {}
    '400':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request body was not a single JSON object.
      description: Occurs when the client did not send a valid JSON object in the
        request body.
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not allowed to edit the content of the work package.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** edit work package
      headers: {}
    '404':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The specified query does not exist.
      description: |-
        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)
      headers: {}
    '422':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: name
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: The name might not be blank.
      description: |-
        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`)
      headers: {}
  tags:
  - Queries
  description: |-
    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.
  operationId: Edit_Query
  requestBody:
    content:
      application/json:
        schema:
          example:
            name: New query name
          properties:
            name:
              type: string
          type: object
  summary: Edit Query