openapi: 3.2.0
info:
  title: analytics/discovery-agent/adaptive-cards Owl 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: owl
paths:
  /api/analytics/discovery-agent/adaptive-cards:
    get:
      tags:
      - owl
      summary: List Adaptive Cards
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdaptiveCards'
          description: Returns the requested Adaptive Cards.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Bad request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Unauthorized, JWT invalid or not provided.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: 'Forbidden, the requesting JWT does not allow retrieval of Adaptive Cards (error code: OWL-003).'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
          description: Internal server error.
      parameters:
      - in: query
        name: analysisTypes
        style: form
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisTypeEnum'
          example:
          - spikesUp
          - spikesDown
        explode: false
        required: false
        description: 'Filter by analysis type. Repeat the parameter to include multiple types. When this parameter is present, all matching results are returned regardless of ranking.

          '
      - in: query
        name: appIds
        style: form
        schema:
          type: array
          items:
            type: string
        explode: false
        examples:
          singleAppId:
            value:
            - 9b89de1e-9a1b-11ef-9974-563d08542bef
            summary: Single app
          multipleAppIds:
            value:
            - 9b89de1e-9a1b-11ef-9974-563d08542bef
            summary: Multiple apps
        required: false
        description: 'Filter by app ID(s). Use this to scope results to specific apps. When combined with measures, returns only cards matching BOTH criteria (AND logic). Repeat the parameter to supply multiple app IDs (OR logic within appIds).


          **Recommendation:** Use consistent parameter order for better HTTP cache hit rates:

          1. appIds (if present)

          2. measures (if present)

          3. other filters

          4. pagination (limit, next, prev)


          **Example - One app, multiple measures:**

          `?appIds=app-123&measures=Sum(Sales)&measures=Avg(Revenue)&measures=Count(Orders)`


          **Example - Multiple apps, one measure:**

          `?appIds=app-retail&appIds=app-wholesale&measures=Sum(Sales)`


          **Example - Multiple apps, multiple measures:**

          `?appIds=app-sales&appIds=app-hr&measures=Sum(Revenue)&measures=Avg(Salary)`

          '
      - in: query
        name: breakdowns
        style: form
        schema:
          type: array
          items:
            type: string
            example: Region:EMEA
        explode: false
        examples:
          singleBreakdown:
            value:
            - Region:EMEA
            summary: Single breakdown selection
          multipleBreakdowns:
            value:
            - Region:EMEA
            summary: Multiple breakdown selections
        required: false
        description: 'Filter by one or more breakdown selections in the form `dimension:value` (example `Region:EMEA`). Values are selected from the UI dropdown — not free text — and should match available dimension/value pairs.

          Repeat the parameter to supply multiple breakdowns; results match any of the provided breakdown pairs.

          '
      - in: query
        name: categories
        style: form
        schema:
          type: array
          items:
            type: string
        explode: false
        examples:
          single:
            value:
            - 6db0fd8e-2115-4ac6-8d51-1729adbc4cfd
            summary: Single category
          multiple:
            value:
            - 6db0fd8e-2115-4ac6-8d51-1729adbc4cfd
            summary: Multiple categories
        required: false
        description: Filter by category IDs from the business glossary. Category filtering is not currently applied to the result set.
      - in: query
        name: comparisonPeriods
        style: form
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AggregationFrequencyEnum'
        explode: false
        required: false
        description: 'Filter by comparison period. Example values: `D`, `W`, `M`, `Q`, `Y`. When this parameter is present, all matching results are returned regardless of ranking.

          '
      - in: query
        name: dimensions
        style: form
        schema:
          type: array
          items:
            type: string
        explode: false
        examples:
          singleDimension:
            value:
            - Date
            summary: Single dimension
          multipleDimensions:
            value:
            - Date
            summary: Multiple dimensions
        required: false
        description: Filter by dimension(s). Matching is case-sensitive; leading and trailing whitespace will be trimmed. Repeat the parameter to supply multiple dimensions.
      - in: query
        name: limit
        schema:
          type: integer
          format: int32
          default: 10
          maximum: 100
          minimum: 1
        required: false
        description: The maximum number of resources to return for a request. The limit must be an integer between 1 and 100 (inclusive).
      - in: query
        name: measures
        style: form
        schema:
          type: array
          items:
            type: string
        explode: false
        examples:
          singleMeasure:
            value:
            - Sum(Sales)
            summary: Single measure selection
          multipleMeasures:
            value:
            - Sum(Sales)
            summary: Multiple measure selections
        required: false
        description: Filter by measure(s). Matching is case-sensitive; leading and trailing whitespace will be trimmed. Repeat the parameter to supply multiple measures.
      - in: query
        name: metricIds
        style: form
        schema:
          type: array
          items:
            type: string
        explode: false
        examples:
          oneMetricId:
            value:
            - 123e4567-e89b-12d3-a456-426614174000
            summary: Single metric
          multipleMetricIds:
            value:
            - 123e4567-e89b-12d3-a456-426614174000
            summary: Multiple metrics
        required: false
        description: Filter by metric ID. Repeat the parameter to supply multiple IDs. When omitted, returns cards for all metrics visible to the caller.
      - in: query
        name: next
        schema:
          type: integer
          format: int32
          example: 10
        required: false
        description: The numeric offset to the next page of resources. Provide either the next or prev parameter, but not both.
      - in: query
        name: prev
        schema:
          type: integer
          format: int32
          example: 5
        required: false
        description: The numeric offset to the previous page of resources. Provide either the next or prev parameter, but not both.
      - in: query
        name: sort
        schema:
          enum:
          - creationTime
          - +creationTime
          - -creationTime
          type: string
          default: +creationTime
        required: false
        description: The field to sort by, with +/- prefix indicating sort order
      - in: query
        name: timeRangeEnd
        schema:
          type: string
          format: date-time
          example: '2023-10-31T00:00:00.000Z'
        required: false
        description: Exclusive upper bound for filtering by analysis result end time. Use ISO 8601 format.
      - in: query
        name: timeRangeStart
        schema:
          type: string
          format: date-time
          example: '2023-10-01T00:00:00.000Z'
        required: false
        description: Inclusive lower bound for filtering by analysis result end time. Use ISO 8601 format.
      - in: query
        name: type
        schema:
          enum:
          - measures
          - dimensions
          - breakdowns
          type: string
        required: false
        description: Filter by Adaptive Card category. When omitted, cards from all categories are returned.
      - in: header
        name: Authorization
        schema:
          type: string
        required: true
        description: JWT containing tenant credentials.
      description: 'Retrieves Adaptive Cards for in-app metrics. Supports fetching a single card by metric ID or multiple cards by a list of metric IDs. Supports filtering by app IDs, measures, dimensions, categories, breakdown dimensions, analysis types, and triggered time range. When filtering by measures, use the `appIds` parameter to scope results to specific apps, as the same measure expression can exist across multiple apps.


        When called without any filter parameters, only the top-ranked result per metric is returned. When any filtering parameter is supplied (`metricIds`, `dimensions`, `measures`, `appIds`, `breakdowns`, `analysisTypes`, `comparisonPeriods`, `timeRangeStart`, `timeRangeEnd`), ranking is not applied and all matching results are returned.'
      operationId: getAdaptiveCards
      x-qlik-stability: stable
      x-qlik-visibility: public
      x-qlik-deprecated: false
      x-qlik-tier:
        tier: '1'
        limit: 1000
components:
  schemas:
    ComparisonType:
      enum:
      - '>'
      - '>='
      - <
      - <=
      - '> <'
      - '>= <='
      type: string
      example: '>'
      description: Comparison operation type
    BreakdownSearchFilter:
      type: object
      required:
      - searchType
      properties:
        searchType:
          $ref: '#/components/schemas/SearchType'
        searchString:
          type: string
          example: Marketing
          description: String to search for. If empty, all dimension values are analyzed.
      description: Search-based filtering configuration. If searchString is empty or not provided, all dimension values will be analyzed (no filtering applied).
    SearchType:
      enum:
      - contains
      - exactMatch
      - startsWith
      - endsWith
      - beginningOfWord
      type: string
      example: contains
      description: Search operation type
    Error:
      type: object
      required:
      - code
      - title
      properties:
        code:
          type: string
          example: OWL-001
          description: The error code is in the form of 'OWL-xxx', ranges from 'OWL-001' to 'OWL-016'.
        title:
          type: string
        detail:
          type: string
    Href:
      type: object
      example:
        href: http://example.com
      properties:
        href:
          type: string
          format: uri
          example: http://example.com
    AdaptiveCardsLinks:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/Href'
        prev:
          $ref: '#/components/schemas/Href'
        self:
          $ref: '#/components/schemas/Href'
    ValueType:
      enum:
      - calculated
      - fixed
      type: string
      example: fixed
      description: Whether the value is calculated or fixed
    AnalysisTypeEnum:
      enum:
      - recordHigh
      - recordLow
      - aboveModel
      - belowModel
      - spikesUp
      - spikesDown
      - newBaseLine
      - trendChanges
      type: string
      example: spikesUp
      description: Type of analysis performed on the in-app metric.
    ConditionType:
      enum:
      - general
      - compare
      type: string
      example: general
      description: Condition evaluation type
    AdaptiveCard:
      type: object
      description: Adaptive Card
    FormattedInAppMetricDefinition:
      type: object
      required:
      - name
      - dimension
      - measure
      - analysisTypes
      properties:
        name:
          type: string
          example: Profit by region Europe
        status:
          $ref: '#/components/schemas/StatusEnum'
        measure:
          type: string
          example: Sum({<Region='Europe'>} Profit)
        upwardIs:
          $ref: '#/components/schemas/UpwardIsEnum'
        dimension:
          type: string
          example: ShipDate
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Categories'
          example:
          - glossaryId: fe7df4a8-abb4-42da-95e7-4ee8db22a7cb
            categoryIds:
            - 6db0fd8e-2115-4ac6-8d51-1729adbc4cfd
        glossaryId:
          type: string
          example: 5a7482f5-892a-4194-9f48-366ccb48a1e7
          description: The ID of the glossary that the in-app metric belongs to.
        description:
          type: string
          example: This metric shows the profit by region in Europe.
          description: A description of the in-app metric.
        analysisTypes:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisTypeEnum'
          example:
          - recordHigh
          - aboveModel
          - spikesUp
        comparisonPeriods:
          type: array
          items:
            $ref: '#/components/schemas/AggregationFrequencyEnum'
          example:
          - D
          - W
          - M
          - Q
          - Y
        breakDownDimensions:
          type: array
          items:
            $ref: '#/components/schemas/BreakDownDimension'
        nextExecutionOffset:
          type: integer
          example: 7
          description: Number of days to offset the execution of analyses for this aggregation period.
    AggregationFrequencyEnum:
      enum:
      - D
      - W
      - M
      - Q
      - Y
      type: string
      example: D
      description: Comparison period for the analysis.
    FormattedInAppMetricRecord:
      type: object
      required:
      - id
      - tenantId
      - appId
      - userId
      - creationTime
      - updateTime
      - definition
      - status
      - links
      properties:
        id:
          type: string
          example: 67cab2cf3d74cae279940b99
          description: The ID of the in-app metric in the database.
        appId:
          type: string
          example: 9b89de1e-9a1b-11ef-9974-563d08542bef
          description: The ID of the app.
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Href'
        status:
          $ref: '#/components/schemas/StatusEnum'
        userId:
          type: string
          example: FyPG6xWp6prDU6BXQ3g7LY9gWR_YRkkx
          description: The ID of the user who created the in-app-metric.
        tenantId:
          type: string
          example: efSCcpNYuayTysONkUcE3F80zYQ_LV9w
          description: The ID of the tenant who owns the in-app metric.
        definition:
          $ref: '#/components/schemas/FormattedInAppMetricDefinition'
        updateTime:
          type: string
          example: '2023-10-01T12:00:00Z'
          description: The time when the in-app metric was last updated.
        creationTime:
          type: string
          example: '2023-10-01T12:00:00Z'
          description: The time when the in-app metric was created.
    StatusEnum:
      enum:
      - 0
      - 1
      type: integer
      example: 1
      description: Status of the in app metrics (0 - inactive, 1 - active).
    Errors:
      type: object
      example:
        errors:
        - code: OWL-001
          title: Invalid request.
          details: ''
        - code: OWL-002
          title: Unauthorized access.
          detail: You may need to login to access this resource.
        - code: OWL-003
          title: Resource not found.
          detail: The resource either never existed, or may have been deleted.
        - code: OWL-013
          title: The analysis can not be started because the analysis frequency quota has been met.
          detail: ''
        - code: OWL-015
          title: Too many breakdown dimensions.
          detail: ''
        - code: OWL-016
          title: Too many breakdown values.
          detail: ''
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Categories:
      type: object
      properties:
        glossaryId:
          type: string
          example: 5a7482f5-892a-4194-9f48-366ccb48a1e7
          description: The ID of the glossary that the category belongs to.
        categoryIds:
          type: array
          items:
            type: string
            example: 6db0fd8e-2115-4ac6-8d51-1729adbc4cfd
            description: Category ID
          example:
          - 6db0fd8e-2115-4ac6-8d51-1729adbc4cfd
          description: The IDs of the categories.
    BreakdownFilter:
      type: object
      example:
        type: values
        values:
        - Europe
        - Asia
        - North America
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/BreakdownFilterType'
        search:
          $ref: '#/components/schemas/BreakdownSearchFilter'
        values:
          type: array
          items:
            type: string
            example: Europe
            description: A dimension value to filter by.
          example:
          - Europe
          - Asia
          description: List of values to filter by (used when type is Values)
        exclude:
          type: boolean
          default: false
          description: 'When set to true, the filter values are excluded from analysis instead of included.

            - If exclude is false or omitted, only the matched values are analyzed (max 50).

            - If exclude is true, all dimension values EXCEPT the matched values are analyzed (max 50).

            '
        condition:
          $ref: '#/components/schemas/BreakdownConditionFilter'
        topBottom:
          $ref: '#/components/schemas/BreakdownTopBottomFilter'
      description: Filter configuration for a breakdown dimension
    BreakdownTopBottomFilter:
      type: object
      required:
      - type
      - unit
      - number
      properties:
        type:
          $ref: '#/components/schemas/TopBottomType'
        unit:
          $ref: '#/components/schemas/TopBottomUnit'
        number:
          type: integer
          example: 10
          description: Number of top/bottom values to select
      description: Top/bottom filtering configuration
    UpwardIsEnum:
      enum:
      - 0
      - 1
      - -1
      type: integer
      example: 1
      description: Indicates whether an increase in the metric is considered neutral (0), positive (1) or negative (-1).
    TopBottomUnit:
      enum:
      - numerical
      - percentage
      type: string
      example: numerical
      description: Unit for top/bottom selection
    TopBottomType:
      enum:
      - top
      - bottom
      type: string
      example: top
      description: Whether to select top or bottom values
    BreakDownDimension:
      type: object
      example:
        filter:
          type: values
          values:
          - Europe
          - Asia
        values:
        - Europe
        - Asia
        dimension: Region
      required:
      - dimension
      properties:
        filter:
          $ref: '#/components/schemas/BreakdownFilter'
        values:
          type: array
          items:
            type: string
            example: Europe
            description: A dimension value to include in the breakdown.
          example:
          - Europe
          - Asia
          description: List of values (kept for backward compatibility)
        dimension:
          type: string
          example: Region
          description: The dimension name
      description: 'Breakdown dimension with filtering capabilities.

        - `dimension` is required.

        - `values` and `filter` are optional. If both are omitted (or `values` is empty and `filter` is null), the API interprets this as "analyze all values" for the given dimension.

        '
    AggregationType:
      enum:
      - sum
      - avg
      - count
      - max
      - min
      type: string
      example: sum
      description: Aggregation operation type
    BreakdownFilterType:
      enum:
      - values
      - search
      - condition
      - topBottom
      type: string
      example: values
      description: Type of breakdown filter
    BreakdownConditionFilter:
      type: object
      required:
      - conditionType
      - comparisonType
      properties:
        field:
          type: string
          example: Sales
          description: Primary field for calculated values
        value:
          type: number
          example: 100
          description: Fixed numeric value (used by single comparisons with Compare.Fixed and General.Fixed)
        field2:
          type: string
          example: Cost
          description: Additional field used only by General.Calculated for single comparisons
        toField:
          type: string
          example: MaxPrice
          description: Upper bound field for range comparisons with Calculated value type (used with > < or >= <=)
        toValue:
          type: number
          example: 500
          description: Upper bound value for range comparisons with Fixed value type (used with > < or >= <=)
        fromField:
          type: string
          example: MinPrice
          description: Lower bound field for range comparisons with Calculated value type (used with > < or >= <=)
        fromValue:
          type: number
          example: 100
          description: Lower bound value for range comparisons with Fixed value type (used with > < or >= <=)
        valueType:
          $ref: '#/components/schemas/ValueType'
        aggregation:
          $ref: '#/components/schemas/AggregationType'
        aggregation2:
          $ref: '#/components/schemas/AggregationType'
        conditionType:
          $ref: '#/components/schemas/ConditionType'
        toAggregation:
          $ref: '#/components/schemas/AggregationType'
        comparisonType:
          $ref: '#/components/schemas/ComparisonType'
        fromAggregation:
          $ref: '#/components/schemas/AggregationType'
      description: 'Condition-based filtering configuration. Supports single comparisons (>, >=, <, <=) and range comparisons (> <, >= <=).


        **Single Comparisons:**

        - Compare type: Uses `value` (Fixed) or `aggregation`+`field` (Calculated)

        - General type: Uses `aggregation`+`field` and either `value` (Fixed) or `aggregation2`+`field2` (Calculated)


        **Range Comparisons (> < or >= <=):**

        - Compare type: Uses `fromValue`+`toValue` (Fixed) or `fromAggregation`+`fromField`+`toAggregation`+`toField` (Calculated)

        - General type: Uses `aggregation`+`field` plus either `fromValue`+`toValue` (Fixed) or `fromAggregation`+`fromField`+`toAggregation`+`toField` (Calculated)

        '
    AdaptiveCards:
      type: object
      required:
      - data
      - links
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AdaptiveCard'
        links:
          $ref: '#/components/schemas/AdaptiveCardsLinks'
        inAppMetrics:
          type: array
          items:
            $ref: '#/components/schemas/FormattedInAppMetricRecord'