openapi: 3.2.0
info:
  title: apps Insight Analyses 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: insight-analyses
paths:
  /api/v1/apps/{appId}/insight-analyses:
    get:
      tags:
      - insight-analyses
      summary: Returns information about supported analyses for the app's data model.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisDescriptorResponse'
          description: The request is successfully processed and information about supported analyses is returned.
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not found
        '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: path
        name: appId
        schema:
          type: string
          format: uid
        required: true
        description: Qlik Sense app identifier
      - in: header
        name: accept-language
        schema:
          type: string
        required: false
        description: language specified as an ISO-639-1 code. Defaults to 'en' (English).
      operationId: getAnalyses
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: special
        limit: 500
  /api/v1/apps/{appId}/insight-analyses/actions/recommend:
    post:
      tags:
      - insight-analyses
      summary: Returns analysis recommendations in response to a natural language question, a…
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisRecommendationResponse'
          description: The request is successfully processed and recommendations are returned.
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid Business Logic
        '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: path
        name: appId
        schema:
          type: string
          format: uid
        required: true
        description: Qlik Sense app identifier
      - in: header
        name: accept-language
        schema:
          type: string
        required: false
        description: language specified as an ISO-639-1 code. Defaults to 'en' (English).
      operationId: getRecommendations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalysisRecommendRequest'
        required: true
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: special
        limit: 500
  /api/v1/apps/{appId}/insight-analyses/model:
    get:
      tags:
      - insight-analyses
      summary: Returns information about model used to make analysis recommendations.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisModelResponse'
          description: The request is successfully processed and information about model is returned.
        '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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Invalid Business Logic
        '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: path
        name: appId
        schema:
          type: string
          format: uid
        required: true
        description: Qlik Sense app identifier
      operationId: getBusinessModel
      x-qlik-visibility: public
      x-qlik-stability: stable
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: special
        limit: 500
components:
  schemas:
    AnalysisRecommendationResponseDetail:
      type: object
      required:
      - recAnalyses
      properties:
        nluInfo:
          type: array
          items:
            $ref: '#/components/schemas/PartialNluInfo'
        recAnalyses:
          type: array
          items:
            $ref: '#/components/schemas/RecommendedAnalysis'
    AnalysisDetails:
      type: object
      properties:
        title:
          type: string
        analysis:
          $ref: '#/components/schemas/Analysis'
        analysisGroup:
          $ref: '#/components/schemas/AnalysisGroup'
    AnalysisRecommendationResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisRecommendationResponseDetail'
    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
    Href:
      type: object
      properties:
        href:
          type: string
          format: uri
          example: http://example.com
    AnalysisDescriptorResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisDescriptor'
        links:
          $ref: '#/components/schemas/Links'
    ChartType:
      enum:
      - barchart
      - combochart
      - distributionplot
      - kpi
      - linechart
      - map
      - scatterplot
      - table
      type: string
      description: Chart type given to current recommendation
    Analysis:
      enum:
      - breakdown
      - changePoint
      - comparison
      - contribution
      - correlation
      - fact
      - mutualInfo
      - rank
      - spike
      - trend
      - values
      type: string
    RecommendFieldItem:
      type: object
      properties:
        name:
          type: string
        overrides:
          $ref: '#/components/schemas/FieldOverride'
      description: 'structure for providing fields in recommendation request, user can retrieve the fields using insight-analyses/model endpoint

        '
    RecommendMasterItem:
      type: object
      properties:
        libId:
          type: string
        overrides:
          type: object
          properties:
            format:
              $ref: '#/components/schemas/numberFormat'
      description: 'structure for providing master items in recommendation request, user can retrieve the libId of master item using insight-analyses/model endpoint

        '
    AnalysisDescriptor:
      type: object
      properties:
        id:
          type: string
        compositions:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisComposition'
        supportsMasterItems:
          type: boolean
          description: If analysis can work with master items (default is true)
        requiresAutoCalendarPeriod:
          type: boolean
          description: Used for period-specific analyses to indicate the defined or available calendar period must be of type autoCalendar
        requiresDefinedAnalysisPeriod:
          type: boolean
          description: Used for period-specific analyses to indicate the measure must be associated with one or more analysis periods
        requiresAvailableAnalysisPeriod:
          type: boolean
          description: Used for period-specific analyses to indicate the temporal dimension must be associated with one or more analysis periods
    Links:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/Href'
        prev:
          $ref: '#/components/schemas/Href'
        self:
          $ref: '#/components/schemas/Href'
    AnalysisModelResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisModelResponseDetail'
        links:
          $ref: '#/components/schemas/Links'
    Classifications:
      type: array
      items:
        enum:
        - dimension
        - measure
        - temporal
        - city
        - address
        - boolean
        - country
        - date
        - email
        - geographical
        - geoPoint
        - geoPolygon
        - hour
        - latitude
        - monetary
        - ordinal
        - percentage
        - postalCode
        - quarter
        - stateProvince
        - timestamp
        - week
        - weekDay
        - year
        - yearDay
        type: string
      description: classification defines the default role that attribute can play in an analysis
    FieldOverride:
      type: object
      properties:
        classifications:
          type: array
          items:
            type: string
        defaultAggregation:
          type: string
      x-qlik-visibility: public
    SimplifiedClassifications:
      type: array
      items:
        enum:
        - dimension
        - measure
        - temporal
        - geographical
        type: string
    AnalysisComposition:
      type: object
      properties:
        dims:
          $ref: '#/components/schemas/CompositionMinMax'
        geos:
          $ref: '#/components/schemas/CompositionMinMax'
        msrs:
          $ref: '#/components/schemas/CompositionMinMax'
        items:
          $ref: '#/components/schemas/CompositionMinMax'
        temporals:
          $ref: '#/components/schemas/CompositionMinMax'
        description:
          type: object
          properties:
            long:
              type: string
            short:
              type: string
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      x-qlik-visibility: public
    AnalysisModelItemField:
      type: object
      properties:
        name:
          type: string
          description: populated only for fields
        isHidden:
          type: boolean
          default: false
          description: whether the field is hidden in business logic
        classifications:
          $ref: '#/components/schemas/Classifications'
        simplifiedClassifications:
          $ref: '#/components/schemas/SimplifiedClassifications'
    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.
    AnalysisModelItemMasterItem:
      type: object
      properties:
        libId:
          type: string
          description: only available for master items
        caption:
          type: string
        isHidden:
          type: boolean
          default: false
          description: whether the master item is hidden in business logic
        classifications:
          $ref: '#/components/schemas/Classifications'
        simplifiedClassifications:
          $ref: '#/components/schemas/SimplifiedClassifications'
    AnalysisRecommendRequest:
      type: object
      oneOf:
      - $ref: '#/components/schemas/RecommendNaturalLangQuery'
      - $ref: '#/components/schemas/RecommendItems'
      description: "Request payload can be of two types, using natural language query or consist of fields or master items and optional target analysis.\nIn below examples, consider sales as a master item and product as field, so to get recommendations using sales and product,\nyou can utilize below three approaches, also you can set language parameter in headers as part of accept-language.\nExamples:\n```\n{\n  'text': 'show me sales by product'\n}\n```\n```\n{\n  'fields': [\n    {\n      'name': 'product'\n    }\n  ],\n  'libItems': [\n    {\n      libId: 'NwQfJ'\n    }\n  ]\n}\n```\n```\n{\n  'fields': [\n    {\n      'name': 'product'\n    }\n  ],\n  'libItems': [\n    {\n      'libId': 'NwQfJ'\n    }\n  ],\n  'targetAnalysis': {\n    'id': 'rank-rank'\n  }\n}\n```\n"
    RecommendItems:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/RecommendFieldItem'
        libItems:
          type: array
          items:
            $ref: '#/components/schemas/RecommendMasterItem'
        targetAnalysis:
          type: object
          properties:
            id:
              type: string
              description: id of the target analysis, returned by the GET insight-analyses endpoint
    RecommendNaturalLangQuery:
      type: object
      required:
      - text
      properties:
        text:
          type: string
          description: The NL query.
    AnalysisGroup:
      enum:
      - anomaly
      - brekadown
      - comparison
      - correl
      - fact
      - list
      - mutualInfo
      - rank
      type: string
    AnalysisModelResponseDetail:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisModelItemField'
        masterItems:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisModelItemMasterItem'
        isLogicalModelEnabled:
          type: boolean
          description: if the analysis model is constructed based on a user-defined business-logic (as opposed to a default one)
        isDefinedLogicalModelValid:
          type: boolean
          description: set only if previous property is true, to indicate if the business logic passes validation
    numberFormat:
      type: object
      properties:
        qDec:
          type: string
        qFmt:
          type: string
        qThou:
          type: string
        qType:
          type: string
        qnDec:
          type: number
        qUseThou:
          type: number
    RecommendedAnalysisCore:
      type: object
      properties:
        options:
          type: object
          description: (chart options + hypercube definition)
        analysis:
          $ref: '#/components/schemas/AnalysisDetails'
        chartType:
          $ref: '#/components/schemas/ChartType'
        relevance:
          type: number
          description: percentage of selected items in the analysis to the overall items passed to the endpoint
    RecommendedAnalysis:
      type: object
      allOf:
      - $ref: '#/components/schemas/RecommendedAnalysisCore'
      - type: object
        properties:
          parts:
            type: array
            items:
              $ref: '#/components/schemas/RecommendedAnalysisCore'
            description: part analyses (only for macro analyses)
    CompositionMinMax:
      type: object
      properties:
        max:
          type: number
        min:
          type: number
      description: Upper and lower bounds for items of specific classification types