OpenProject API V3 (Stable) — Queries

naftiko: 1.0.0-alpha2
info:
  label: OpenProject API V3 (Stable) — Queries
  description: 'OpenProject API V3 (Stable) — Queries. 16 operations. Lead operation: View default query for project. Self-contained
    Naftiko capability covering one Openproject business surface.'
  tags:
  - Openproject
  - Queries
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    OPENPROJECT_API_KEY: OPENPROJECT_API_KEY
capability:
  consumes:
  - type: http
    namespace: openproject-queries
    baseUri: https://qa.openproject-edge.com
    description: OpenProject API V3 (Stable) — Queries business capability. Self-contained, no shared references.
    resources:
    - name: api-v3-projects-id-queries-default
      path: /api/v3/projects/{id}/queries/default
      operations:
      - name: viewdefaultqueryforproject
        method: GET
        description: View default query for project
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Id of the project the default query is requested for
          required: true
        - name: filters
          in: query
          type: string
          description: JSON specifying filter conditions.
        - name: offset
          in: query
          type: integer
          description: Page number inside the queries' result collection of work packages.
        - name: pageSize
          in: query
          type: integer
          description: Number of elements to display per page for the queries' result collection of work packages.
        - name: sortBy
          in: query
          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.
        - name: groupBy
          in: query
          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 criteri
        - name: showSums
          in: query
          type: boolean
          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 '
        - name: timestamps
          in: query
          type: string
          description: 'Indicates the timestamps to filter by when showing changed attributes on work packages. Values can
            be either ISO8601 dates, ISO8601 durations and the following '
        - name: timelineVisible
          in: query
          type: boolean
          description: Indicates whether the timeline should be shown.
        - name: showHierarchies
          in: query
          type: boolean
          description: Indicates whether the hierarchy mode should be enabled.
    - name: api-v3-projects-id-queries-schema
      path: /api/v3/projects/{id}/queries/schema
      operations:
      - name: viewschemaforprojectqueries
        method: GET
        description: View schema for project queries
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Project id
          required: true
    - name: api-v3-queries
      path: /api/v3/queries
      operations:
      - name: listqueries
        method: GET
        description: List queries
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: filters
          in: query
          type: string
          description: JSON specifying filter conditions.
      - name: createquery
        method: POST
        description: Create query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v3-queries-available_projects
      path: /api/v3/queries/available_projects
      operations:
      - name: availableprojectsforquery
        method: GET
        description: Available projects for query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-v3-queries-default
      path: /api/v3/queries/default
      operations:
      - name: viewdefaultquery
        method: GET
        description: View default query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: filters
          in: query
          type: string
          description: JSON specifying filter conditions.
        - name: offset
          in: query
          type: integer
          description: Page number inside the queries' result collection of work packages.
        - name: pageSize
          in: query
          type: integer
          description: Number of elements to display per page for the queries' result collection of work packages.
        - name: sortBy
          in: query
          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.
        - name: groupBy
          in: query
          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 criteri
        - name: showSums
          in: query
          type: boolean
          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 '
        - name: timestamps
          in: query
          type: string
          description: 'Indicates the timestamps to filter by when showing changed attributes on work packages. Values can
            be either ISO8601 dates, ISO8601 durations and the following '
        - name: timelineVisible
          in: query
          type: boolean
          description: Indicates whether the timeline should be shown.
        - name: timelineZoomLevel
          in: query
          type: string
          description: Indicates in what zoom level the timeline should be shown. Valid values are  `days`, `weeks`, `months`,
            `quarters`, and `years`.
        - name: showHierarchies
          in: query
          type: boolean
          description: Indicates whether the hierarchy mode should be enabled.
    - name: api-v3-queries-form
      path: /api/v3/queries/form
      operations:
      - name: querycreateform
        method: POST
        description: Query Create Form
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v3-queries-schema
      path: /api/v3/queries/schema
      operations:
      - name: viewschemaforglobalqueries
        method: GET
        description: View schema for global queries
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-v3-queries-id
      path: /api/v3/queries/{id}
      operations:
      - name: deletequery
        method: DELETE
        description: Delete query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Query id
          required: true
      - name: viewquery
        method: GET
        description: View query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Query id
          required: true
        - name: filters
          in: query
          type: string
          description: JSON specifying filter conditions.
        - name: offset
          in: query
          type: integer
          description: Page number inside the queries' result collection of work packages.
        - name: pageSize
          in: query
          type: integer
          description: Number of elements to display per page for the queries' result collection of work packages.
        - name: columns
          in: query
          type: string
          description: Selected columns for the table view.
        - name: sortBy
          in: query
          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.
        - name: groupBy
          in: query
          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 criteri
        - name: showSums
          in: query
          type: boolean
          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 '
        - name: timestamps
          in: query
          type: string
          description: 'Indicates the timestamps to filter by when showing changed attributes on work packages. Values can
            be either ISO8601 dates, ISO8601 durations and the following '
        - name: timelineVisible
          in: query
          type: boolean
          description: Indicates whether the timeline should be shown.
        - name: timelineLabels
          in: query
          type: string
          description: Overridden labels in the timeline view
        - name: highlightingMode
          in: query
          type: string
          description: Highlighting mode for the table view.
        - name: highlightedAttributes
          in: query
          type: string
          description: Highlighted attributes mode for the table view when `highlightingMode` is `inline`. When set to `[]`
            all highlightable attributes will be returned as `highlight
        - name: showHierarchies
          in: query
          type: boolean
          description: Indicates whether the hierarchy mode should be enabled.
      - name: editquery
        method: PATCH
        description: Edit Query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Query id
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v3-queries-id-form
      path: /api/v3/queries/{id}/form
      operations:
      - name: queryupdateform
        method: POST
        description: Query Update Form
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Query id
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-v3-queries-id-star
      path: /api/v3/queries/{id}/star
      operations:
      - name: starquery
        method: PATCH
        description: Star query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Query id
          required: true
    - name: api-v3-queries-id-unstar
      path: /api/v3/queries/{id}/unstar
      operations:
      - name: unstarquery
        method: PATCH
        description: Unstar query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Query id
          required: true
    - name: api-v3-workspace-id-queries-schema
      path: /api/v3/workspace/{id}/queries/schema
      operations:
      - name: viewschemaforworkspacequeries
        method: GET
        description: View schema for workspace queries
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Project id
          required: true
    - name: api-v3-workspaces-id-queries-default
      path: /api/v3/workspaces/{id}/queries/default
      operations:
      - name: viewdefaultqueryforworkspace
        method: GET
        description: View default query for workspace
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Id of the workspace the default query is requested for
          required: true
        - name: filters
          in: query
          type: string
          description: JSON specifying filter conditions.
        - name: offset
          in: query
          type: integer
          description: Page number inside the queries' result collection of work packages.
        - name: pageSize
          in: query
          type: integer
          description: Number of elements to display per page for the queries' result collection of work packages.
        - name: sortBy
          in: query
          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.
        - name: groupBy
          in: query
          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 criteri
        - name: showSums
          in: query
          type: boolean
          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 '
        - name: timestamps
          in: query
          type: string
          description: 'Indicates the timestamps to filter by when showing changed attributes on work packages. Values can
            be either ISO8601 dates, ISO8601 durations and the following '
        - name: timelineVisible
          in: query
          type: boolean
          description: Indicates whether the timeline should be shown.
        - name: showHierarchies
          in: query
          type: boolean
          description: Indicates whether the hierarchy mode should be enabled.
    authentication:
      type: basic
      username: '{{env.OPENPROJECT_USER}}'
      password: '{{env.OPENPROJECT_PASS}}'
  exposes:
  - type: rest
    namespace: openproject-queries-rest
    port: 8080
    description: REST adapter for OpenProject API V3 (Stable) — Queries. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api/v3/projects/{id}/queries/default
      name: api-v3-projects-id-queries-default
      description: REST surface for api-v3-projects-id-queries-default.
      operations:
      - method: GET
        name: viewdefaultqueryforproject
        description: View default query for project
        call: openproject-queries.viewdefaultqueryforproject
        with:
          id: rest.id
          filters: rest.filters
          offset: rest.offset
          pageSize: rest.pageSize
          sortBy: rest.sortBy
          groupBy: rest.groupBy
          showSums: rest.showSums
          timestamps: rest.timestamps
          timelineVisible: rest.timelineVisible
          showHierarchies: rest.showHierarchies
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/projects/{id}/queries/schema
      name: api-v3-projects-id-queries-schema
      description: REST surface for api-v3-projects-id-queries-schema.
      operations:
      - method: GET
        name: viewschemaforprojectqueries
        description: View schema for project queries
        call: openproject-queries.viewschemaforprojectqueries
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries
      name: api-v3-queries
      description: REST surface for api-v3-queries.
      operations:
      - method: GET
        name: listqueries
        description: List queries
        call: openproject-queries.listqueries
        with:
          filters: rest.filters
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createquery
        description: Create query
        call: openproject-queries.createquery
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/available-projects
      name: api-v3-queries-available-projects
      description: REST surface for api-v3-queries-available_projects.
      operations:
      - method: GET
        name: availableprojectsforquery
        description: Available projects for query
        call: openproject-queries.availableprojectsforquery
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/default
      name: api-v3-queries-default
      description: REST surface for api-v3-queries-default.
      operations:
      - method: GET
        name: viewdefaultquery
        description: View default query
        call: openproject-queries.viewdefaultquery
        with:
          filters: rest.filters
          offset: rest.offset
          pageSize: rest.pageSize
          sortBy: rest.sortBy
          groupBy: rest.groupBy
          showSums: rest.showSums
          timestamps: rest.timestamps
          timelineVisible: rest.timelineVisible
          timelineZoomLevel: rest.timelineZoomLevel
          showHierarchies: rest.showHierarchies
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/form
      name: api-v3-queries-form
      description: REST surface for api-v3-queries-form.
      operations:
      - method: POST
        name: querycreateform
        description: Query Create Form
        call: openproject-queries.querycreateform
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/schema
      name: api-v3-queries-schema
      description: REST surface for api-v3-queries-schema.
      operations:
      - method: GET
        name: viewschemaforglobalqueries
        description: View schema for global queries
        call: openproject-queries.viewschemaforglobalqueries
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/{id}
      name: api-v3-queries-id
      description: REST surface for api-v3-queries-id.
      operations:
      - method: DELETE
        name: deletequery
        description: Delete query
        call: openproject-queries.deletequery
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: viewquery
        description: View query
        call: openproject-queries.viewquery
        with:
          id: rest.id
          filters: rest.filters
          offset: rest.offset
          pageSize: rest.pageSize
          columns: rest.columns
          sortBy: rest.sortBy
          groupBy: rest.groupBy
          showSums: rest.showSums
          timestamps: rest.timestamps
          timelineVisible: rest.timelineVisible
          timelineLabels: rest.timelineLabels
          highlightingMode: rest.highlightingMode
          highlightedAttributes: rest.highlightedAttributes
          showHierarchies: rest.showHierarchies
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: editquery
        description: Edit Query
        call: openproject-queries.editquery
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/{id}/form
      name: api-v3-queries-id-form
      description: REST surface for api-v3-queries-id-form.
      operations:
      - method: POST
        name: queryupdateform
        description: Query Update Form
        call: openproject-queries.queryupdateform
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/{id}/star
      name: api-v3-queries-id-star
      description: REST surface for api-v3-queries-id-star.
      operations:
      - method: PATCH
        name: starquery
        description: Star query
        call: openproject-queries.starquery
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/queries/{id}/unstar
      name: api-v3-queries-id-unstar
      description: REST surface for api-v3-queries-id-unstar.
      operations:
      - method: PATCH
        name: unstarquery
        description: Unstar query
        call: openproject-queries.unstarquery
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/workspace/{id}/queries/schema
      name: api-v3-workspace-id-queries-schema
      description: REST surface for api-v3-workspace-id-queries-schema.
      operations:
      - method: GET
        name: viewschemaforworkspacequeries
        description: View schema for workspace queries
        call: openproject-queries.viewschemaforworkspacequeries
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v3/workspaces/{id}/queries/default
      name: api-v3-workspaces-id-queries-default
      description: REST surface for api-v3-workspaces-id-queries-default.
      operations:
      - method: GET
        name: viewdefaultqueryforworkspace
        description: View default query for workspace
        call: openproject-queries.viewdefaultqueryforworkspace
        with:
          id: rest.id
          filters: rest.filters
          offset: rest.offset
          pageSize: rest.pageSize
          sortBy: rest.sortBy
          groupBy: rest.groupBy
          showSums: rest.showSums
          timestamps: rest.timestamps
          timelineVisible: rest.timelineVisible
          showHierarchies: rest.showHierarchies
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: openproject-queries-mcp
    port: 9090
    transport: http
    description: MCP adapter for OpenProject API V3 (Stable) — Queries. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: view-default-query-project
      description: View default query for project
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewdefaultqueryforproject
      with:
        id: tools.id
        filters: tools.filters
        offset: tools.offset
        pageSize: tools.pageSize
        sortBy: tools.sortBy
        groupBy: tools.groupBy
        showSums: tools.showSums
        timestamps: tools.timestamps
        timelineVisible: tools.timelineVisible
        showHierarchies: tools.showHierarchies
      outputParameters:
      - type: object
        mapping: $.
    - name: view-schema-project-queries
      description: View schema for project queries
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewschemaforprojectqueries
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: list-queries
      description: List queries
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.listqueries
      with:
        filters: tools.filters
      outputParameters:
      - type: object
        mapping: $.
    - name: create-query
      description: Create query
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: openproject-queries.createquery
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: available-projects-query
      description: Available projects for query
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.availableprojectsforquery
      outputParameters:
      - type: object
        mapping: $.
    - name: view-default-query
      description: View default query
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewdefaultquery
      with:
        filters: tools.filters
        offset: tools.offset
        pageSize: tools.pageSize
        sortBy: tools.sortBy
        groupBy: tools.groupBy
        showSums: tools.showSums
        timestamps: tools.timestamps
        timelineVisible: tools.timelineVisible
        timelineZoomLevel: tools.timelineZoomLevel
        showHierarchies: tools.showHierarchies
      outputParameters:
      - type: object
        mapping: $.
    - name: query-create-form
      description: Query Create Form
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: openproject-queries.querycreateform
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: view-schema-global-queries
      description: View schema for global queries
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewschemaforglobalqueries
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-query
      description: Delete query
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: openproject-queries.deletequery
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: view-query
      description: View query
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewquery
      with:
        id: tools.id
        filters: tools.filters
        offset: tools.offset
        pageSize: tools.pageSize
        columns: tools.columns
        sortBy: tools.sortBy
        groupBy: tools.groupBy
        showSums: tools.showSums
        timestamps: tools.timestamps
        timelineVisible: tools.timelineVisible
        timelineLabels: tools.timelineLabels
        highlightingMode: tools.highlightingMode
        highlightedAttributes: tools.highlightedAttributes
        showHierarchies: tools.showHierarchies
      outputParameters:
      - type: object
        mapping: $.
    - name: edit-query
      description: Edit Query
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: openproject-queries.editquery
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: query-update-form
      description: Query Update Form
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: openproject-queries.queryupdateform
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: star-query
      description: Star query
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: openproject-queries.starquery
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: unstar-query
      description: Unstar query
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: openproject-queries.unstarquery
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: view-schema-workspace-queries
      description: View schema for workspace queries
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewschemaforworkspacequeries
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: view-default-query-workspace
      description: View default query for workspace
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: openproject-queries.viewdefaultqueryforworkspace
      with:
        id: tools.id
        filters: tools.filters
        offset: tools.offset
        pageSize: tools.pageSize
        sortBy: tools.sortBy
        groupBy: tools.groupBy
        showSums: tools.showSums
        timestamps: tools.timestamps
        timelineVisible: tools.timelineVisible
        showHierarchies: tools.showHierarchies
      outputParameters:
      - type: object
        mapping: $.