Natural language

Ask natural languages questions and context aware partial questions against applications enabled for conversational analytics or a specific app to receive Insight Advisor generated responses and suggestions

Download specification

Endpoints

POST

/v1/questions/actions/ask
POST

/v1/questions/actions/filter

Facts

Rate limit	Tier 2 (100 requests per minute)
Categories	embed

Header Parameters

qlik-web-integration-idstring

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

Request Body

Required

application/json

application/jsonobject
Show application/json properties
- appobject
  
  Show app properties
  
  idstring
  
  namestring
- langstring
  
  The language to assume when parsing, specified as an ISO-639-1 code. Defaults to 'en' (English).
- textstring
  Required
  
  The sentence that will be parsed.
- disableFollowupsboolean
  
  The flag specifies whether to disable follow-up recommendations.
  
  default = false
- disableNarrativeboolean
  
  Flag that specifies whether the narratives should be generated for the user query or not.
  
  default = false
- recommendationIdstring
  
  property that contains the Id of the recommendation for which the response should be generated.
- clearEntityContextboolean
  
  Flag that clears the entity context.
  
  default = false
- visualizationTypesarray of strings
  
  Specify visualizationTypes for only which visualization object should be provided if enableVisualizations is set to true. For eg. ['linechart', 'barchart']
- enableVisualizationsboolean
  
  Flag that specifies whether visualization object should be provided or not.
  
  default = false
- disableConversationContextboolean
  
  Flag that specifies either to enable converastion context.
  
  default = false

Responses

200

application/json

The sentence is not created as an app was not specified, but matching apps are suggested

application/jsonobject
Show application/json properties
- appsarray of objects
  
  Show apps properties
  
  idstring
  
  namestring
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.
- nluInfoobject
  
  Show nluInfo properties
  
  elementsarray of objects
  
  Show elements properties
  
  textstring
  
  typestring
  
  entityboolean
  
  isFilterboolean
  
  typeNamestring
  
  errorTextstring
  
  filterTextstring
  
  typeTranslatedstring
  
  filterFieldNamestring
- conversationalResponseobject
  
  Show conversationalResponse properties
  
  appsarray of objects
  
  Show apps properties
  
  idstring
  
  namestring
  
  responsesarray of objects
  
  Show responses properties
  
  typestring
  
  imageUrlstring
  
  infoTypestring
  
  sentenceobject
  
  Show sentence properties
  
  textstring
  
  narrativeobject
  
  Show narrative properties
  
  textstring
  
  infoValuesarray of arrays
  
  One of:
  
  array of strings
  
  array of objects
  
  Show properties
  
  idstring
  
  namestring
  
  errorMessagestring
  
  followupSentencestring
  
  renderVisualizationobject
  
  Show renderVisualization properties
  
  dataobject
  
  Data object should be used to render visualization
  
  languagestring
  
  contextInfostring
  
  For contextual responses, this string contains a list of entities that are used to produce the response.
  
  drillDownURIstring
  
  The URL with the query injected to insight advisor of the app to which the query belongs.
  
  sentenceWithMatchesstring

201

application/json

The sentence created

The attributes of sentences.

application/jsonobject

The attributes of sentences.
Show application/json properties
- appsarray of objects
  
  Show apps properties
  
  idstring
  
  namestring
- nluInfoobject
  
  Show nluInfo properties
  
  elementsarray of objects
  
  Show elements properties
  
  textstring
  
  typestring
  
  entityboolean
  
  isFilterboolean
  
  typeNamestring
  
  errorTextstring
  
  filterTextstring
  
  typeTranslatedstring
  
  filterFieldNamestring
- conversationalResponsearray of objects
  
  A list of conversational responses.
  
  Show conversationalResponse properties
  
  appsarray of objects
  
  Show apps properties
  
  idstring
  
  namestring
  
  responsesarray of objects
  
  Show responses properties
  
  typestring
  
  imageUrlstring
  
  infoTypestring
  
  sentenceobject
  
  Show sentence properties
  
  textstring
  
  narrativeobject
  
  Show narrative properties
  
  textstring
  
  infoValuesarray of arrays
  
  One of:
  
  array of strings
  
  array of objects
  
  Show properties
  
  idstring
  
  namestring
  
  errorMessagestring
  
  followupSentencestring
  
  renderVisualizationobject
  
  Show renderVisualization properties
  
  dataobject
  
  Data object should be used to render visualization
  
  languagestring
  
  contextInfostring
  
  For contextual responses, this string contains a list of entities that are used to produce the response.
  
  drillDownURIstring
  
  The URL with the query injected to insight advisor of the app to which the query belongs.
  
  sentenceWithMatchesstring

400

application/json

Bad request. The payload is not formed correctly.

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

401

application/json

User is not authorized

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

422

application/json

Unprocessable entity. The payload contains fields that are invalid, such as too long of a query.

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

default

application/json

Unexpected error.

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

POST /v1/questions/actions/ask

curl "https://your-tenant.us.qlikcloud.com/api/v1/questions/actions/ask" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"app":{"id":"string","name":"string"},"lang":"string","text":"string","disableFollowups":false,"disableNarrative":false,"recommendationId":"string","clearEntityContext":false,"visualizationTypes":["string"],"enableVisualizations":false,"disableConversationContext":false}'

const https = require('https')
  const data = JSON.stringify({"app":{"id":"string","name":"string"},"lang":"string","text":"string","disableFollowups":false,"disableNarrative":false,"recommendationId":"string","clearEntityContext":false,"visualizationTypes":["string"],"enableVisualizations":false,"disableConversationContext":false})
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/questions/actions/ask',
    'method': 'POST',
    'headers': {
      'Content-type': 'application/json',
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
  req.write(data)

qlik question ask \
--app-id="string" \
--app-name="string" \
--lang="string" \
--recommendationId="string" \
--text="string" \
--visualizationTypes='"string"'

Request

{
  "app": {
    "id": "string",
    "name": "string"
  },
  "lang": "string",
  "text": "string",
  "disableFollowups": false,
  "disableNarrative": false,
  "recommendationId": "string",
  "clearEntityContext": false,
  "visualizationTypes": [
    "string"
  ],
  "enableVisualizations": false,
  "disableConversationContext": false
}

Response

{
  "apps": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "errors": [
    {
      "code": "string",
      "meta": {},
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      }
    }
  ],
  "nluInfo": {
    "elements": [
      {
        "text": "string",
        "type": "string",
        "entity": true,
        "isFilter": true,
        "typeName": "string",
        "errorText": "string",
        "filterText": "string",
        "typeTranslated": "string",
        "filterFieldName": "string"
      }
    ]
  },
  "conversationalResponse": {
    "apps": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "responses": [
      {
        "type": "string",
        "imageUrl": "string",
        "infoType": "string",
        "sentence": {
          "text": "string"
        },
        "narrative": {
          "text": "string"
        },
        "infoValues": [
          [
            "string"
          ]
        ],
        "errorMessage": "string",
        "followupSentence": "string",
        "renderVisualization": {
          "data": {},
          "language": "string"
        }
      }
    ],
    "contextInfo": "string",
    "drillDownURI": "string",
    "sentenceWithMatches": "string"
  }
}

Facts

Rate limit	Tier 2 (100 requests per minute)
Categories	embed

Query Parameters

limitinteger

The preferred number of entries returned

minimum = 1, maximum = 100, default = 100, format = int32, default = 100
pagestring

A cursor pointing to the page of data to retrieve.
sortstring

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.

Can be one of: "createdAt""updatedAt""+createdAt""+updatedAt""-createdAt""-updatedAt"

default = "+createdAt"

Request Body

Required

application/json

application/jsonobject
Show application/json properties
- filterstring
  Required
  
  The advanced filtering to use for the query. Refer to RFC 7644 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')

Responses

200

application/json

If the user has access to any of the provided app id

application/jsonobject
Show application/json properties
- dataarray of objects
  
  Show data properties
  
  idstring
  Required
  
  Unique record id stored in database
  
  format = "uuid"
  
  appsarray of objects
  
  Metadata for app
  
  Show apps properties
  
  idstring
  
  namestring
  
  space_idstring
  
  space_namestring
  
  space_typestring
  
  limited_accessboolean
  
  last_reload_datestring
  
  format = "date-time"
  
  langstring
  
  language selected for query from insight advisor or insight advisor chat or third party api
  
  appIdstring
  Required
  
  Qlik sense app id that is being used to answer the question
  
  format = "uuid"
  
  appNamestring
  
  Qlik sense app name that is being used to answer the question
  
  nluInfoarray of objects
  
  Contains break down of the asked question in the form of tokens with their classification.
  
  Show nluInfo properties
  
  rolestring
  
  Role of the token or phrase from query
  
  Can be one of: "dimension""measure""date"
  
  textstring
  
  Matching token or phrase from query
  
  typestring
  
  Type of token from query
  
  Can be one of: "field""filter""master_dimension""master_measure""custom_analysis"
  
  fieldNamestring
  
  Qlik sense application field selected for given token or phrase
  
  fieldValuestring
  
  Filter value found from query
  
  versionstring
  Required
  
  Version of the metric model
  
  feedbackarray of objects
  
  Any feedback from the user about a given recommendation
  
  Show feedback properties
  
  commentstring
  
  chartTypestring
  
  analysisTypestring
  
  recommendationLikedboolean
  Required
  
  recommendationDislikedboolean
  Required
  
  recommendationAddedToHubboolean
  Required
  
  recommendationAddedToSheetboolean
  Required
  
  tenantIdstring
  
  Qlik sense tenant Id
  
  format = "uuid"
  
  channelIdstring
  
  Source from which conversation is happening
  
  chartTypestring
  
  Chart type for given query. For insight advisor it would be 'native' and for insight advisor chat, it could be 'static' or 'responsive'
  
  createdAtstring
  RequiredFilterable
  
  Record created date
  
  format = "date-time"
  
  createdBystring
  
  Qlik sense user id who is interacting with insight advisor or insight advisor chat or third party api
  
  queryTextstring
  
  Query asked by user in insight advisor or insight advisor or third party api
  
  queryTypestring
  
  Nature of query being asked during the conversation e.g. query, applist, measurelist, dimensionlist
  
  Can be one of: "appList""appSuggested""dimensionList""exploreThisFurther""followup""greetings""measureList""query""sampleQuestion"
  
  responsesobject
  
  Provides info what was included in response for given query
  
  Show responses properties
  
  hasChartboolean
  
  Chart was provided
  
  hasInsightsboolean
  
  Narrative was provided
  
  hasSuggestionsboolean
  
  Suggestion questions was provided
  
  hasMetadataAppsboolean
  
  App list was provided
  
  hasSampleQueriesboolean
  
  Sample questions was provided
  
  hasMetadataMeasuresboolean
  
  Measures list was provided
  
  hasMetadataDimensionsboolean
  
  Dimensions list was provided
  
  stopWordsarray of strings
  
  Tokens from question parsed which are ignored
  
  updatedAtstring
  RequiredFilterable
  
  Record modified date
  
  format = "date-time"
  
  queryErrorboolean
  
  default = false
  
  questionIdstring
  Required
  
  Unique id assigned to user query
  
  queryOriginstring
  
  Refers to source from where narrative request is called
  
  Can be one of: "askQuestion""iaAnalysis""iaAssetsPanel"
  
  default = "askQuestion"
  
  recommendationsarray of objects
  
  Visualisation recommendation specs for the query
  
  Show recommendations properties
  
  dimsarray of strings
  
  Dimension(s) considered for recommendation
  
  msrsarray of strings
  
  Measure(s) considered for recommendation
  
  analysisstring
  
  Can be one of: "breakdown""changePoint""comparison""contribution""correlation""fact""mutualInfo""rank""spike""trend""values"
  
  chartTypestring
  
  Chart type given to current recommendation
  
  Can be one of: "barchart""combochart""distributionplot""kpi""linechart""map""scatterplot""table"
  
  relevancenumber
  
  analysisGroupstring
  
  Can be one of: "anomaly""brekadown""comparison""correl""fact""list""mutualInfo""rank"
  
  isContextualQueryboolean
  
  Boolean value indicates whether given query is contextual or not. It would be false for insight advisor
  
  default = false
  
  unmatchedEntitiesarray of strings
  
  Tokens parsed as entities but not matched with app's field/dimension/measure
- metaobject
  
  Show meta properties
  
  totalinteger
  Required
  
  The total number of metrics matching the current filter.
- linksobject
  
  Show links properties
  
  nextobject
  
  Show next properties
  
  hrefstring
  
  format = "uri"
  
  prevobject
  
  Show prev properties
  
  hrefstring
  
  format = "uri"
  
  selfobject
  
  Show self properties
  
  hrefstring
  
  format = "uri"

400

application/json

Bad request. The payload is not formed correctly.

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

401

application/json

User is not authorized

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

422

application/json

Unprocessable entity. The payload contains fields that are invalid, such as too long of a query.

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

500

application/json

Internal server error

application/jsonobject
Show application/json properties
- errorsarray of objects
  
  An error object.
  
  Show errors properties
  
  codestring
  Required
  
  The error code.
  
  metaobject
  
  Additional properties relating to the error.
  
  titlestring
  Required
  
  Summary of the problem.
  
  detailstring
  
  A human-readable explanation specific to this occurrence of the problem.
  
  sourceobject
  
  References to the source of the error.
  
  Show source properties
  
  pointerstring
  
  A JSON Pointer to the property that caused the error.
  
  parameterstring
  
  The URI query parameter that caused the error.

POST /v1/questions/actions/filter

curl "https://your-tenant.us.qlikcloud.com/api/v1/questions/actions/filter" \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer <access_token>" \
-d '{"filter":"string"}'

const https = require('https')
  const data = JSON.stringify({"filter":"string"})
  const options =   {
    'hostname': 'https://your-tenant.us.qlikcloud.com',
    'port': 443,
    'path': '/api/v1/questions/actions/filter',
    'method': 'POST',
    'headers': {
      'Content-type': 'application/json',
      'Authorization': 'Bearer <access_token>'
    }
  }
  const req = https.request(options)
  req.write(data)

qlik question filter \
--filter="string"

Request

{
  "filter": "string"
}

Response

{
  "data": [
    {
      "id": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "apps": [
        {
          "id": "string",
          "name": "string",
          "space_id": "string",
          "space_name": "string",
          "space_type": "string",
          "limited_access": true,
          "last_reload_date": "2018-10-30T07:06:22Z"
        }
      ],
      "lang": "string",
      "appId": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "appName": "string",
      "nluInfo": [
        {
          "role": "dimension",
          "text": "string",
          "type": "field",
          "fieldName": "string",
          "fieldValue": "string"
        }
      ],
      "version": "string",
      "feedback": [
        {
          "comment": "string",
          "chartType": "string",
          "analysisType": "string",
          "recommendationLiked": true,
          "recommendationDisliked": true,
          "recommendationAddedToHub": true,
          "recommendationAddedToSheet": true
        }
      ],
      "tenantId": "c35f4b70-3ce4-4a30-b62b-2aef16943bc4",
      "channelId": "string",
      "chartType": "string",
      "createdAt": "2018-10-30T07:06:22Z",
      "createdBy": "string",
      "queryText": "string",
      "queryType": "appList",
      "responses": {
        "hasChart": true,
        "hasInsights": true,
        "hasSuggestions": true,
        "hasMetadataApps": true,
        "hasSampleQueries": true,
        "hasMetadataMeasures": true,
        "hasMetadataDimensions": true
      },
      "stopWords": [
        "string"
      ],
      "updatedAt": "2018-10-30T07:06:22Z",
      "queryError": false,
      "questionId": "string",
      "queryOrigin": "askQuestion",
      "recommendations": [
        {
          "dims": [
            "string"
          ],
          "msrs": [
            "string"
          ],
          "analysis": "breakdown",
          "chartType": "barchart",
          "relevance": 42,
          "analysisGroup": "anomaly"
        }
      ],
      "isContextualQuery": false,
      "unmatchedEntities": [
        "string"
      ]
    }
  ],
  "meta": {
    "total": 42
  },
  "links": {
    "next": {
      "href": "http://example.com"
    },
    "prev": {
      "href": "http://example.com"
    },
    "self": {
      "href": "http://example.com"
    }
  }
}

Natural language

Endpoints

Returns the generated response for parsed chat queries, if no app was specified nor present in conversation context, suggests matching apps.

Facts

Header Parameters

Request Body

Responses

200

201

400

401

422

default

Request

Response

Returns NL metrics based on provided app IDs the user has access to.

Facts

Query Parameters

Request Body

Responses

200

400

401

422

500

Request

Response