Qlik Sense Questions API

openapi: 3.2.0
info:
  title: Questions 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: Questions
paths:
  /api/v1/questions/actions/ask:
    post:
      tags:
      - Questions
      summary: Returns the generated response for parsed chat queries, if no app was specified…
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryNotCreated'
          description: The sentence is not created as an app was not specified, but matching apps are suggested
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryCreated'
          description: The sentence created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad request. The payload is not formed correctly.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: User is not authorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: 'Unprocessable entity. The payload contains fields

            that are invalid, such as too long of a query.

            '
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unexpected error.
      parameters:
      - in: header
        name: qlik-web-integration-id
        schema:
          type: string
        required: false
        description: This header is only required for external clients or mashups for QCS, this value of this property should be the id of the web integration set up for the external client/mashup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryCreate'
        required: true
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
      operationId: postApiV1QuestionsActionsAsk
      x-operation-id-source: derived
  /api/v1/questions/actions/filter:
    post:
      tags:
      - Questions
      summary: Returns NL metrics based on provided app IDs the user has access to
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLMetricsResponse'
          description: If the user has access to any of the provided app id
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad request. The payload is not formed correctly.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: User is not authorized
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: 'Unprocessable entity. The payload contains fields

            that are invalid, such as too long of a query.

            '
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal server error
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 100
          minimum: 1
        required: false
        description: The preferred number of entries returned
      - in: query
        name: page
        schema:
          type: string
        required: false
        description: A cursor pointing to the page of data to retrieve.
      - in: query
        name: sort
        schema:
          enum:
          - createdAt
          - updatedAt
          - +createdAt
          - +updatedAt
          - -createdAt
          - -updatedAt
          type: string
          default: +createdAt
        required: false
        description: 'A single field from the data model on which to sort the response. The ''+'' or ''-'' operator may be used to specify ascending or desending order.

          '
      operationId: filterMetrics
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NLMetricsRequest'
        required: true
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '2'
        limit: 100
components:
  schemas:
    AnalysisGroup:
      enum:
      - anomaly
      - brekadown
      - comparison
      - correl
      - fact
      - list
      - mutualInfo
      - rank
      type: string
    QueryCreated:
      type: object
      properties:
        apps:
          type: array
          items:
            $ref: '#/components/schemas/QlikApp'
        nluInfo:
          $ref: '#/components/schemas/NluInfo'
        conversationalResponse:
          type: array
          items:
            $ref: '#/components/schemas/QueryResponse'
          description: A list of conversational responses.
      description: The attributes of sentences.
      x-qlik-visibility: public
    NLResponses:
      type: object
      properties:
        hasChart:
          type: boolean
          description: Chart was provided
        hasInsights:
          type: boolean
          description: Narrative was provided
        hasSuggestions:
          type: boolean
          description: Suggestion questions was provided
        hasMetadataApps:
          type: boolean
          description: App list was provided
        hasSampleQueries:
          type: boolean
          description: Sample questions was provided
        hasMetadataMeasures:
          type: boolean
          description: Measures list was provided
        hasMetadataDimensions:
          type: boolean
          description: Dimensions list was provided
      description: Provides info what was included in response for given query
    NLMetricRecord:
      type: object
      required:
      - id
      - createdAt
      - updatedAt
      - appId
      - questionId
      - version
      properties:
        id:
          type: string
          format: uuid
          description: Unique record id stored in database
        apps:
          type: array
          items:
            $ref: '#/components/schemas/AppMetadata'
        lang:
          type: string
          description: language selected for query from insight advisor or insight advisor chat or third party api
        appId:
          type: string
          format: uuid
          description: Qlik sense app id that is being used to answer the question
        appName:
          type: string
          description: Qlik sense app name that is being used to answer the question
        nluInfo:
          type: array
          items:
            $ref: '#/components/schemas/PartialNluInfo'
        version:
          type: string
          description: Version of the metric model
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/RecFeedback'
        tenantId:
          type: string
          format: uuid
          description: Qlik sense tenant Id
        channelId:
          type: string
          description: Source from which conversation is happening
        chartType:
          type: string
          description: Chart type for given query. For insight advisor it would be 'native' and for insight advisor chat, it could be 'static' or 'responsive'
        createdAt:
          type: string
          format: date-time
          description: Record created date
          x-qlik-filterable: true
        createdBy:
          type: string
          description: Qlik sense user id who is interacting with insight advisor or insight advisor chat or third party api
        queryText:
          type: string
          description: Query asked by user in insight advisor or insight advisor or third party api
        queryType:
          enum:
          - appList
          - appSuggested
          - dimensionList
          - exploreThisFurther
          - followup
          - greetings
          - measureList
          - query
          - sampleQuestion
          type: string
          description: Nature of query being asked during the conversation e.g. query, applist, measurelist, dimensionlist
        responses:
          $ref: '#/components/schemas/NLResponses'
        stopWords:
          type: array
          items:
            type: string
          description: Tokens from question parsed which are ignored
        updatedAt:
          type: string
          format: date-time
          description: Record modified date
          x-qlik-filterable: true
        queryError:
          type: boolean
          default: false
        questionId:
          type: string
          description: Unique id assigned to user query
        queryOrigin:
          enum:
          - askQuestion
          - iaAnalysis
          - iaAssetsPanel
          type: string
          default: askQuestion
          description: Refers to source from where narrative request is called
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/NLMetricRecommendation'
        isContextualQuery:
          type: boolean
          default: false
          description: Boolean value indicates whether given query is contextual or not. It would be false for insight advisor
        unmatchedEntities:
          type: array
          items:
            type: string
          description: Tokens parsed as entities but not matched with app's field/dimension/measure
    NLMetricsRequest:
      required:
      - filter
      properties:
        filter:
          type: string
          description: 'The advanced filtering to use for the query. Refer to [RFC 7644](https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2) for the syntax.


            Filter on createdAt and updatedAt fields are encouraged and support `eq`, `ne`, `gt`, `ge`, `lt`, `le` comparison operators along with `and` and `or` logical operators.


            Filter on tenantId field is not supported.


            `co`, `sw` and `ew` operators are not supported.


            Examples:

            ```

            appId eq ''appId1''

            ```

            ```

            (appId eq ''appId1'' or appId eq ''appId2'')

            ```

            ```

            (appId eq ''appId1'' or appId eq ''appId2'') and (createdAt gt ''2022-08-03T00:00:00.000Z'' and createdAt lt ''2022-08-04T00:00:00.000Z'')

            ```


            ```

            (appId eq ''appId1'') and (createdAt ge ''2022-08-03T00:00:00.000Z'')

            ```


            ```

            (appId eq ''appId1'') and (createdAt le ''2022-08-23:59:59.000Z'')

            ```


            ```

            (appId eq ''appId1'') and (questionId eq ''12345'')

            ```

            '
    NLMetricRecommendation:
      type: object
      properties:
        dims:
          type: array
          items:
            type: string
          description: Dimension(s) considered for recommendation
        msrs:
          type: array
          items:
            type: string
          description: Measure(s) considered for recommendation
        analysis:
          $ref: '#/components/schemas/Analysis'
        chartType:
          $ref: '#/components/schemas/ChartType'
        relevance:
          type: number
        analysisGroup:
          $ref: '#/components/schemas/AnalysisGroup'
      description: Visualisation recommendation specs for the query
    NarrativeResponse:
      properties:
        text:
          type: string
      x-qlik-visibility: public
    Analysis:
      enum:
      - breakdown
      - changePoint
      - comparison
      - contribution
      - correlation
      - fact
      - mutualInfo
      - rank
      - spike
      - trend
      - values
      type: string
    QueryNotCreated:
      type: object
      properties:
        apps:
          type: array
          items:
            $ref: '#/components/schemas/QlikApp'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        nluInfo:
          $ref: '#/components/schemas/NluInfo'
        conversationalResponse:
          $ref: '#/components/schemas/QueryResponse'
      x-qlik-visibility: public
    NluInfo:
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/NluInfoElements'
      x-qlik-visibility: public
    QueryResponse:
      type: object
      properties:
        apps:
          type: array
          items:
            $ref: '#/components/schemas/QlikApp'
        responses:
          type: array
          items:
            $ref: '#/components/schemas/ConversationalResponsePart'
        contextInfo:
          type: string
          description: For contextual responses, this string contains a list of entities that are used to produce the response.
        drillDownURI:
          type: string
          description: The URL with the query injected to insight advisor of the app to which the query belongs.
        sentenceWithMatches:
          type: string
      x-qlik-visibility: public
    QueryCreate:
      type: object
      required:
      - text
      properties:
        app:
          $ref: '#/components/schemas/QlikApp'
        lang:
          type: string
          description: 'The language to assume when parsing, specified as an ISO-639-1 code.

            Defaults to ''en'' (English).

            '
        text:
          type: string
          description: The sentence that will be parsed.
        disableFollowups:
          type: boolean
          default: false
          description: The flag specifies whether to disable follow-up recommendations.
        disableNarrative:
          type: boolean
          default: false
          description: Flag that specifies whether the narratives should be generated for the user query or not.
        recommendationId:
          type: string
          description: property that contains the Id of the recommendation for which the response should be generated.
        clearEntityContext:
          type: boolean
          default: false
          description: Flag that clears the entity context.
        visualizationTypes:
          type: array
          items:
            type: string
          description: Specify visualizationTypes for only which visualization object should be provided if enableVisualizations is set to true. For eg. ['linechart', 'barchart']
        enableVisualizations:
          type: boolean
          default: false
          description: Flag that specifies whether visualization object should be provided or not.
        disableConversationContext:
          type: boolean
          default: false
          description: Flag that specifies either to enable converastion context.
      x-qlik-visibility: public
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      x-qlik-visibility: public
    ConversationalResponsePart:
      properties:
        type:
          type: string
        imageUrl:
          type: string
        infoType:
          type: string
        sentence:
          properties:
            text:
              type: string
        narrative:
          $ref: '#/components/schemas/NarrativeResponse'
        infoValues:
          type: array
          items:
            oneOf:
            - type: array
              items:
                type: string
            - type: array
              items:
                $ref: '#/components/schemas/QlikApp'
        errorMessage:
          type: string
        followupSentence:
          type: string
        renderVisualization:
          $ref: '#/components/schemas/RenderVisualization'
      x-qlik-visibility: public
    Href:
      type: object
      properties:
        href:
          type: string
          format: uri
          example: http://example.com
    NLMetricsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NLMetricRecord'
        meta:
          type: object
          readOnly: true
          required:
          - total
          properties:
            total:
              type: integer
              description: The total number of metrics matching the current filter.
        links:
          $ref: '#/components/schemas/Links'
    RenderVisualization:
      properties:
        data:
          type: object
          description: Data object should be used to render visualization
        language:
          type: string
      x-qlik-visibility: public
    QlikApp:
      properties:
        id:
          type: string
        name:
          type: string
      x-qlik-visibility: public
    PartialNluInfo:
      properties:
        role:
          enum:
          - dimension
          - measure
          - date
          type: string
          description: Role of the token or phrase from query
        text:
          type: string
          description: Matching token or phrase from query
        type:
          enum:
          - field
          - filter
          - master_dimension
          - master_measure
          - custom_analysis
          type: string
          description: Type of token from query
        fieldName:
          type: string
          description: Qlik sense application field selected for given token or phrase
        fieldValue:
          type: string
          description: Filter value found from query
      description: Contains break down of the asked question in the form of tokens with their classification.
    ChartType:
      enum:
      - barchart
      - combochart
      - distributionplot
      - kpi
      - linechart
      - map
      - scatterplot
      - table
      type: string
      description: Chart type given to current recommendation
    Links:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/Href'
        prev:
          $ref: '#/components/schemas/Href'
        self:
          $ref: '#/components/schemas/Href'
    AppMetadata:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        space_id:
          type: string
        space_name:
          type: string
        space_type:
          type: string
        limited_access:
          type: boolean
        last_reload_date:
          type: string
          format: date-time
      description: Metadata for app
    Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          description: The error code.
        meta:
          type: object
          description: Additional properties relating to the error.
        title:
          type: string
          description: Summary of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        source:
          type: object
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the property that caused the error.
            parameter:
              type: string
              description: The URI query parameter that caused the error.
          description: References to the source of the error.
      description: An error object.
      x-qlik-visibility: public
    NluInfoElements:
      properties:
        text:
          type: string
        type:
          type: string
        entity:
          type: boolean
        isFilter:
          type: boolean
        typeName:
          type: string
        errorText:
          type: string
        filterText:
          type: string
        typeTranslated:
          type: string
        filterFieldName:
          type: string
      x-qlik-visibility: public
    RecFeedback:
      type: object
      required:
      - recommendationAddedToSheet
      - recommendationAddedToHub
      - recommendationDisliked
      - recommendationLiked
      properties:
        comment:
          type: string
        chartType:
          type: string
        analysisType:
          type: string
        recommendationLiked:
          type: boolean
        recommendationDisliked:
          type: boolean
        recommendationAddedToHub:
          type: boolean
        recommendationAddedToSheet:
          type: boolean
      description: Any feedback from the user about a given recommendation