Qlik Sense Filters API

openapi: 3.2.0
info:
  title: apps Filters API
  version: ''
servers:
- url: https://{tenant}.{region}.qlikcloud.com
  variables:
    region:
      default: us
      description: The region the tenant is hosted in
    tenant:
      default: your-tenant
      description: Name of the tenant that will be called
tags:
- name: Filters
paths:
  /api/v1/apps/{appId}/report-filters:
    get:
      tags:
      - Filters
      summary: Get the filter list
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterList'
          description: The filters have been successfully returned.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Bad request. Malformed syntax, errors in params.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Forbidden, user lacks sufficient permissions to access the resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Internal server error.
      parameters:
      - in: path
        name: appId
        schema:
          type: string
          format: uid
          example: 11ecf638-0be4-4b94-a9e6-91218f34e175
        required: true
        description: Qlik Sense app identifier
      - in: query
        name: filterTypes
        schema:
          type: array
          items:
            enum:
            - REP
            - SUB
            type: string
          minItems: 1
        required: true
        description: The filter type (REP, SUB). REP stands for report bookmark, SUB for subscription bookmark.
      - in: query
        name: filter
        schema:
          type: string
        required: false
        description: 'The advanced filtering to use for the query. Refer to [RFC 7644](https://datatracker.ietf.org/doc/rfc7644/) for the syntax. Cannot be combined with any of the fields marked as deprecated. All conditional statements within this query parameter are case insensitive.

          The following fields support the `co` (contains) operator: `name`, `description`

          The following fields support the `eq` (equals) operator: `id`, `ownerId`

          Example:

          (name co "query1" or description co "query2") and ownerId eq "123"

          '
      - in: query
        name: limit
        schema:
          type: integer
          default: 20
          example: 20
          maximum: 100
          minimum: 1
        required: false
        description: Limit the returned result set
      - in: query
        name: loadType
        schema:
          enum:
          - interactive
          - batch
          type: string
          default: interactive
        description: Load type expressing the kind of request, eg. interactive for report requests from the Web UI, batch for scheduled report generation.
      - in: query
        name: page
        schema:
          type:
          - string
          - 'null'
          example: NzlmNzI5NWMtZGJlZC00Y2Y4LThkNDAtMzQ5ZDU3YzNjMzQ1
        example: NzlmNzI5NWMtZGJlZC00Y2Y4LThkNDAtMzQ5ZDU3YzNjMzQ1
        description: If present, the cursor that starts the page of data that is returned.
      - in: query
        name: sort
        schema:
          type: array
          items:
            enum:
            - +ownerId
            - -ownerId
            - -name
            - +name
            - +description
            - -description
            - +createdAt
            - -createdAt
            - +updatedAt
            - -updatedAt
            type: string
        required: false
        description: Sorting parameters.
      description: List all filters that are present in the given app. Filters allow to reduce the app data visible in a report output. Each filter can contain definitions on one or multiple fields.
      operationId: filtersList
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
    post:
      tags:
      - Filters
      summary: Create a new filter
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter'
          description: The filter has been successfully created.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Bad request, malformed syntax, errors in params or the report request is not valid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Forbidden, user lacks sufficient permissions to access the resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Not found.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Filter name conflict.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Internal server error.
      parameters:
      - in: path
        name: appId
        schema:
          type: string
          format: uid
          example: 11ecf638-0be4-4b94-a9e6-91218f34e175
        required: true
        description: Qlik Sense app identifier
      description: Creates a new report filter which is used to re-apply selections, variables, patches to an engine session.
      operationId: filtersCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FilterRequest'
        required: true
        description: The filter definition.
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
  /api/v1/apps/{appId}/report-filters/{id}:
    get:
      tags:
      - Filters
      summary: Get a filter
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Filter'
          description: The filter has been successfully returned.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Bad request. Malformed syntax, errors in params.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Forbidden, user lacks sufficient permissions to access the resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Internal server error.
      parameters:
      - in: path
        name: appId
        schema:
          type: string
          format: uid
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: Qlik Sense app identifier
      - in: path
        name: id
        schema:
          type: string
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: The filter id identifier (bookmarkId).
      - in: query
        name: loadType
        schema:
          enum:
          - interactive
          - batch
          type: string
          default: interactive
        description: Load type expressing the kind of request, eg. interactive for report requests from the Web UI, batch for scheduled report generation.
      operationId: filtersGet
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
    patch:
      tags:
      - Filters
      summary: Update a filter
      responses:
        '204':
          description: The filter has been successfully patched.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Bad request. Malformed syntax, errors in params.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Forbidden, user lacks sufficient permissions to access the resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Not found.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Filter name conflict. A filter with the same name already exists.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Internal server error.
      parameters:
      - in: path
        name: appId
        schema:
          type: string
          format: uid
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: Qlik Sense app identifier
      - in: path
        name: id
        schema:
          type: string
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: The filter id identifier (bookmarkId).
      operationId: filtersUpdate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchFilter'
        required: true
        description: The filter definition that will replace the existing one.
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
    delete:
      tags:
      - Filters
      summary: Delete a filter
      responses:
        '204':
          description: The filter has been successfully deleted.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Bad request. Malformed syntax, errors in params.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Forbidden, user lacks sufficient permissions to access the resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Internal server error.
      parameters:
      - in: path
        name: appId
        schema:
          type: string
          format: uid
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: Qlik Sense app identifier
      - in: path
        name: id
        schema:
          type: string
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: The filter id identifier (bookmarkId).
      operationId: filtersDelete
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
  /api/v1/apps/{appId}/report-filters/actions/count:
    get:
      tags:
      - Filters
      summary: Get the number of filters for the given app and filter types
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiltersCount'
          description: The count of filters.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Bad request. Malformed syntax, errors in params.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Forbidden, user lacks sufficient permissions to access the resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Not found.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilterErrors'
          description: Internal server error.
      parameters:
      - in: path
        name: appId
        schema:
          type: string
          format: uid
          example: 01562a37-23e3-4b43-865d-84c26122276c
        required: true
        description: Qlik Sense app identifier
      - in: query
        name: filterTypes
        schema:
          type: array
          items:
            enum:
            - REP
            - SUB
            type: string
          example:
          - REP
          minItems: 1
        required: true
        description: The filter type (REP, SUB). REP stands for report bookmark, SUB for subscription bookmark.
      operationId: filtersCount
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
components:
  schemas:
    FilterV1_0:
      type: object
      example:
        fieldsByState:
          $:
          - name: Country
            values:
            - valueType: string
              valueAsText: 1-Argentina
            - valueType: string
              valueAsText: 4-Brazil
            overrideValues: false
            selectExcluded: false
          - name: Order number
            values:
            - valueType: number
              valueAsText: '61300'
              valueAsNumber: 61300
            overrideValues: false
            selectExcluded: false
      properties:
        variables:
          type: array
          items:
            $ref: '#/components/schemas/FilterVariable'
          description: The filter variables.
        fieldsByState:
          type: object
          description: Map of fields to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FilterField'
            maxItems: 125
    FilterField:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: Region
        values:
          type: array
          items:
            $ref: '#/components/schemas/FilterFieldValue'
          minItems: 1
          description: The filter values.
        description:
          type: string
          example: This is the filter description
          x-nullable: true
          description: Gets the resource description.
        overrideValues:
          type: boolean
          example: false
        selectExcluded:
          type: boolean
          example: false
    FiltersCount:
      type: object
      properties:
        total:
          type: number
          format: int32
          example: 20
          readOnly: true
          description: The total number of filters.
    PatchFilter:
      type: array
      items:
        $ref: '#/components/schemas/PatchFilterItem'
    FilterRequest:
      example:
        name: Filter sample
        filterType: REP
        filterV1_0:
          fieldsByState:
            $:
            - name: Country
              values:
              - valueType: string
                valueAsText: 1-Argentina
              - valueType: string
                valueAsText: 4-Brazil
              overrideValues: false
              selectExcluded: false
            - name: Order number
              values:
              - valueType: number
                valueAsText: '61300'
                valueAsNumber: 61300
              overrideValues: false
              selectExcluded: false
        description: this is a filter sample
        filterVersion: filter-1.0
      required:
      - name
      - filterType
      - filterVersion
      properties:
        name:
          type: string
          example: Filter 1
          description: The filter name.
        appId:
          type: string
          example: 1a60c348-4bc6-428a-b4e6-03bde68a5c19
          description: The App ID.
        ownerId:
          type: string
          example: 649173fbc8ffcfde27412b99
          description: The user that owns the filter, if missing the same as the request user.
        filterType:
          $ref: '#/components/schemas/FilterType'
        filterV1_0:
          $ref: '#/components/schemas/FilterV1_0'
        description:
          type: string
          example: This is the filter description
          x-nullable: true
          description: The filter description.
        filterVersion:
          enum:
          - filter-1.0
          - filter-2.0
          type: string
    FilterVariable:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: variable 1
        value:
          type: string
          example: v1
        evaluate:
          type: boolean
          example: true
    FilterType:
      enum:
      - REP
      - SUB
      type: string
    Float64:
      type: number
      format: float64
      x-go-type:
        type: Float64
        import:
          alias: cModels
          package: github.com/qlik-trial/reporting-service/v10/pkg/models
    PatchFilterItem:
      type: object
      required:
      - op
      - path
      - value
      properties:
        op:
          enum:
          - replace
          type: string
          description: operation (replace).
        path:
          enum:
          - /filter
          type: string
          description: A JSON Pointer path (/).
        value:
          type: object
          properties:
            Filter:
              $ref: '#/components/schemas/FilterItemPatch'
          description: The value to be used for this operation. The properties that cannot be patched include id, filterType, appId
      additionalProperties: false
    FilterList:
      type: object
      readOnly: true
      required:
      - data
      - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FilterListItem'
          description: a list of filters containing all the filters properties (like name,description...) except the filter definition (like FilterV1_0)
        links:
          $ref: '#/components/schemas/LinksResponse'
    FilterError:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          example: REP-400000
          description: 'The unique code for the error


            - "REP-400000" Bad request. The server could not understand the request due to invalid syntax.

            - "REP-400008" Selections error.

            - "REP-400015" Bad request in enigma request. The patch value has invalid JSON format.

            - "REP-401000" Unauthorized. The client must authenticate itself to get the requested response.

            - "REP-401001" Unauthorized, bad JWT.

            - "REP-403000" Forbidden. The client does not have access rights to the content.

            - "REP-403001" App forbidden, the user does not have read permission on the app.

            - "REP-403002" Chart type not supported.

            - "REP-404000" Not found. The server can not find the requested resource.

            - "REP-409043" Filter name conflict. The filter name must be unique.

            - "REP-429000" Too many request. The user has sent too many requests in a given amount of time ("rate limiting").

            - "REP-429012" Exceeded max session tenant quota. A tenant has opened too many different sessions at the same time.

            - "REP-429016" Exceeded max session tenant quota per day.

            - "REP-500000" Fail to resolve resource.

            - "REP-503005" Engine unavailable, qix-sessions error no engines available.

            - "REP-503013" Session unavailable. The engine session used to create the report is unavailable.

            - "REP-504042" Context deadline exceeded applying selections of the Filter.

            - "REP-500031" Error creating bookmark.

            - "REP-404032" Bookmark not found after creating the bookmark.

            - "REP-500033" Error destroying bookmark.

            - "REP-404033" Bookmark not found destroying the bookmark.

            - "REP-409043" Dupliacate bookmark name.

            - "REP-429034" Filters quota exceeded.

            - "REP-400044" Missing or renamed field.

            - "REP-403049" Report filter access not allowed.

            '
        title:
          type: string
          example: Bad request. The server could not understand the request due to invalid syntax.
          description: A summary in english explaining what went wrong.
      description: Error occured during the Filter creation.
    LinkResponse:
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
          format: uri
          example: https://tenant.qlik-cloud.com:443/api/v1/apps/816e23e1-03d2-446b-8721-cdee6b5e59cf/report-filters?filter=&filterTypes=REP&filterTypes=REP&limit=20&page=0&sort=%2Bname
      additionalProperties: false
    Filter:
      type: object
      properties:
        id:
          type: string
          example: c61841ac-7b35-4434-aa74-4421f10fc68e
          readOnly: true
          description: The filter ID (bookmarkId).
        name:
          type: string
          example: Filter 1
          description: The filter name.
          x-qlik-filterable: true
        ownerId:
          type: string
          example: 649173fbc8ffcfde27412b99
          description: The user that owns the filter, if missing the same as the request user.
        createdAt:
          type: string
          format: date-time
          example: '2023-08-09T08:19:37.577Z'
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          example: '2023-08-09T08:19:37.577Z'
          readOnly: true
        filterType:
          $ref: '#/components/schemas/FilterType'
        filterV1_0:
          $ref: '#/components/schemas/FilterV1_0'
        description:
          type: string
          example: This is the filter description
          description: The filter description.
          x-qlik-filterable: true
        filterVersion:
          enum:
          - filter-1.0
          - filter-2.0
          type: string
    FilterErrors:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FilterError'
      description: Errors occured during the Filter creation.
    LinksResponse:
      type: object
      example:
        next:
          href: https://tenant.qlik-cloud.com:443/api/v1/apps/816e23e1-03d2-446b-8721-cdee6b5e59cf/report-filters?filter=&filterTypes=REP&filterTypes=REP&limit=20&page=0&sort=%2Bname
        prev:
          href: https://tenant.qlik-cloud.com:443/api/v1/apps/816e23e1-03d2-446b-8721-cdee6b5e59cf/report-filters?filter=&filterTypes=REP&filterTypes=REP&limit=20&page=0&sort=%2Bname
        self:
          href: https://tenant.qlik-cloud.com:443/api/v1/apps/816e23e1-03d2-446b-8721-cdee6b5e59cf/report-filters?filter=&filterTypes=REP&filterTypes=REP&limit=20&page=0&sort=%2Bname
      required:
      - next
      - prev
      - self
      properties:
        next:
          $ref: '#/components/schemas/LinkResponse'
        prev:
          $ref: '#/components/schemas/LinkResponse'
        self:
          $ref: '#/components/schemas/LinkResponse'
      additionalProperties: false
    FilterItemPatch:
      type: object
      properties:
        name:
          type: string
          example: Filter 1
          description: The filter name.
        ownerId:
          type: string
          example: 649173fbc8ffcfde27412b99
          description: The user that owns the filter, if missing the same as the request user.
        filterV1_0:
          $ref: '#/components/schemas/FilterV1_0'
        description:
          type: string
          example: This is the filter description
          description: The filter description.
        filterVersion:
          enum:
          - filter-1.0
          - filter-2.0
          type: string
    FilterFieldValue:
      type: object
      properties:
        valueType:
          enum:
          - string
          - number
          - evaluate
          - search
          type: string
          example: string
        valueAsText:
          type: string
          example: '2001'
        valueAsNumber:
          $ref: '#/components/schemas/Float64'
    FilterListItem:
      type: object
      properties:
        id:
          type: string
          example: c61841ac-7b35-4434-aa74-4421f10fc68e
          readOnly: true
          description: The filter ID (bookmarkId)
        name:
          type: string
          example: Filter 1
          readOnly: true
          description: The filter name.
        ownerId:
          type: string
          example: 649173fbc8ffcfde27412b99
          readOnly: true
          description: The user that owns the filter, if missing the same as the request user.
        createdAt:
          type: string
          format: date-time
          example: '2023-08-09T08:19:37.577Z'
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          example: '2023-08-09T08:19:37.577Z'
          readOnly: true
        filterType:
          $ref: '#/components/schemas/FilterType'
        filterV1_0:
          $ref: '#/components/schemas/FilterV1_0'
        description:
          type: string
          example: This is the filter description
          readOnly: true
          description: The filter description.
        filterVersion:
          enum:
          - filter-1.0
          - filter-2.0
          type: string
          readOnly: true