What can we help you with?

e.g. Getting Started, Build Dashboards

Top

Dataset Management

Follow

Get data

Access data for a widget/dataset defined in Knowi. This supports cached query results and direct query. The query identifier or widget/dataset entityName is used to determine with data to pull. Only one is needed.

Query

GET /api/1.0/datasets

Parameter Type Comments
entityName String Name of the dataset/widget to load data. Example: Regional Sales
identifier String The query identifier to load data. Example: 78SDD2 To obtain:
  • From UI: To retrieve the identifier, go to queries page then query status. Examples: http://recordit.co/TAWtyDCBKS
  • From Management API: the identifier will be called "urlString" in the response properties.
c9SqlFilter String (Optional) SQL like Filter to manipulate the data returned. See #Cloud9QL documentation for supported functions. Example: select * where salesDate > $c9_today
exportFormat String (Optional) Data format to return. Options are (json, csv). Defaults to json if blank.
optimized Boolean (Optional) If True, outputs as 'json' compressed with GZIP. Defaults to False
limit integer (Optional) Number of records to return
runtimeTokens Array of JSON (Optional) Passing runtime tokens for direct queries e.g. `$c9_fieldName1=value1`. Should be urlencoded json of tokens. Example of json: 
[{"parameterName":"$c9_hitsParam$", "parameterValue":3}, {...}]
Urlencoded: 
%5B%7B%22parameterName%22%3A%22%24c9_hitsParam%24%22%2C%20%22parameterValue%22%3A3%7D%5D
Response
HTTP Status Response
200 OK Output example: 
[
  {"name":"shop1","visitors":25},
  {"name":"shop2","visitors":103}
]
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
Example
	curl -i 'https://www.knowi.com/api/1.0/datasets?entityName=sample&runtimeTokens=%5B%7B%22parameterName%22%3A%22%24c9_hitsParam%24%22%2C%20%22parameterValue%22%3A3%7D%5D' -H 'Authorization: Bearer BYuv76PlV116egWnN0RiidqBk7qFTFdc3FSpe7Fwc6D8ie'

 

View (Get Dataset Info)

This endpoint returns the dataset of a given dataset id
Query

GET /api/1.0/datasets/<objectId>

Parameter Comments
objectId Dataset id to view
Response
HTTP Status Response
200 OK Output example: 
{
  "createdDate": 1643744369000,
  "lastModDate": 1643744428000,
  "id": 16171,
  "metadataConfig": "{\"fields\":[{\"fieldName\":\"Bounced\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"Campaign_name\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"Clicks\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"Conversions\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"Customer\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"Date\",\"fieldType\":\"java.util.Date\"},{\"fieldName\":\"Delivered\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"id\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"message_type\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"Opened\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"Sent\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"Spam\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"Week\",\"fieldType\":\"java.util.Date\"}]}",
  "lastUpdateDate": 1643744369000,
  "mongoId": null,
  "mongoConnectUri": "localhost:27017/Some_a3PNFK",
  "customerId": 1033,
  "datasetName": "Test2022-02-01-19-39__5",
  "identifier": "jqGGU7",
  "userId": 10077,
  "refreshMeta": false,
  "injectStreamTime": false,
  "nlpEnabled": true,
  "nlpBotEnabled": true,
  "nlpConfig": null,
  "customer": null,
  "metaData": {
    "fields": [
      {
        "fieldName": "Bounced",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "Campaign_name",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "Clicks",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "Conversions",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "Customer",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "Date",
        "fieldType": "java.util.Date"
      },
      {
        "fieldName": "Delivered",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "id",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "message_type",
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "Opened",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "Sent",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "Spam",
        "fieldType": "java.lang.Integer"
      },
      {
        "fieldName": "Week",
        "fieldType": "java.util.Date"
      }
    ],
    "dataTypes": {
      "Bounced": "java.lang.Integer",
      "Campaign_name": "java.lang.String",
      "Clicks": "java.lang.Integer",
      "Conversions": "java.lang.Integer",
      "Customer": "java.lang.String",
      "Date": "java.util.Date",
      "Delivered": "java.lang.Integer",
      "id": "java.lang.Integer",
      "message_type": "java.lang.String",
      "Opened": "java.lang.Integer",
      "Sent": "java.lang.Integer",
      "Spam": "java.lang.Integer",
      "Week": "java.util.Date"
    },
    "fieldNames": [
      "Bounced",
      "Campaign_name",
      "Clicks",
      "Conversions",
      "Customer",
      "Date",
      "Delivered",
      "id",
      "message_type",
      "Opened",
      "Sent",
      "Spam",
      "Week"
    ]
  },
  "direct": false
}
400 BAD REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to see specified dataset
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/datasets/15130

 

Delete the Dataset

This endpoint is for deleting the dataset of a given dataset id

Query:

curl -i -X DELETE -H "Authorization: Bearer <token>" http://localhost:9090/api/1.0/datasets/<dataset_id>
Parameter Comments
dataset_id Dataset id to delete

It will remove all accessible dataset with taking the dataset id as a parameter.

Query:

curl -i -X DELETE -H "Authorization: Bearer <token>" http://localhost:9090/api/1.0/datasets?name=<dataset_name_url_encoded>
Parameter Comments
dataset_name_url_encoded  Dataset name to delete

It will remove all accessible datasets by taking the same dataset name for that user as a parameter.

Example:

For the dataset delete endpoint which accepts the name, since the name is not unique, there might be multiple datasets with the same name. In this case, we will return code 400 (Bad Request) and show the following message:

{
"message":"More than one dataset with matching name: Copy of Test Save. Please add \"force=true\" to remove all or append the dataset ID to remove a specific one.",
"datasets":[
{
"id":140060,
"datasetName":"Copy of Test Save",
"userId":786,
"username":"anhvo@cloud9charts.com",
"name":"Anh Vo"
},
{
"id":140063,
"datasetName":"Copy of Test Save",
"userId":27566,
"username":"anh@cloud9charts.com",
"name":"anhvo@cloud9charts.com"
}
]
}

Add the parameter “force” which can be set to true to delete all datasets with the same name.

If you pass in “force=true”, the success message will look for example:

curl -i -X DELETE -H "Authorization: Bearer e0Z3DIqtdurha2gzeqMKXg2Kvf4ipY5Sl13JrolDoOrwie" 'http://localhost:9090/api/1.0/datasets?name=Copy%20of%20Test%20Save&force=true'
HTTP/1.1 200
Set-Cookie: JSESSIONID=24660911A36031B8A97873C422AB44DE; Path=/; HttpOnly
Content-Type: application/json
Content-Length: 151
Date: Thu, 30 Mar 2023 23:13:49 GMT
{ "message" : "Successfully removed 2 dataset(s) with name: Copy of Test Save", "documentation_url" : "https://www.knowi.com/docs/managementAPI.html" }

Note: These 2 endpoints will delete all widgets (if still linked to the dataset) and disable the query as well.

 

System Status

The status API is a public-facing API for determining the status of components and subcomponents in the Knowi infrastructure. This endpoint includes an indicator - one of GREEN, YELLOW, or RED, as well as a human description of the blended component status.

Note: This is only available for On-Premise customers and requires additional configuration. Contact support@knowi.com for assistance.

 

Check all components

This Endpoint returns and check all the components
Query

Returns the status of all components

GET /api/1.0/kpi

No parameters
Response
HTTP Status Response
200 OK Lists components and their subcomponents. Components are represented by JSON objects. Output example: 
{
    'checkMySQL': {
        'name': 'MySQL Connectivity',
        'status': 'GREEN',
        'time': 1,
        'statusLevel': 0
    },
    'checkMongoDB': {
        'name': 'MongoDB Connectivity',
        'status': 'RED',
        'time': 0,
        'comment': 'Timed out after 30000 ms while waiting to connect. Client view of cluster state is {type=UNKNOWN, servers=[{address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}]',
        'statusLevel': 2
    },
    'checkMessageMQ': {
        'name': 'Message Queue Connectivity',
        'status': 'YELLOW',
        'time': 0,
        'comment': 'Connector Realtime is not enabled',
        'statusLevel': 1
    },
    'checkHostedConnector': {
        'name': 'Hosted Connector Connectivity',
        'status': 'YELLOW',
        'time': 0,
        'comment': 'Connector Realtime is not enabled',
        'statusLevel': 1
    },
    'checkQueryPreview': {
        'name': 'Query Preview',
        'status': 'RED',
        'time': 0,
        'comment': 'Failed to preview query: Timed out after 30000 ms while waiting to connect. Client view of cluster state is {type=UNKNOWN, servers=[{address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}]',
        'statusLevel': 2
    },
    'checkQuerySaveAndRunNow': {
        'name': 'Query Save and Run Now',
        'status': 'YELLOW',
        'time': 0,
        'comment': 'Connector Realtime is not enabled',
        'statusLevel': 1
    },
    'checkDashboardLoad': {
        'name': 'Dashboard Load',
        'status': 'YELLOW',
        'time': 0,
        'comment': 'There is no dashboard on "system"\'s "admin" user account ',
        'statusLevel': 1
    },
    'checkWidgetLoad': {
        'name': 'Widget Load',
        'status': 'YELLOW',
        'time': 0,
        'comment': 'There is no widget on "system"\'s "admin" user account ',
        'statusLevel': 1
    }
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Missed groupName field
  • Failed to edit group - details saved at server log
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to access KPI
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X GET http://localhost:9090/api/1.0/kpi

 

Check specific component

This endpoint returns the status of a specific component. Possible components are listed below:
Query

GET /api/1.0/kpi/<component>

Available Components Description
checkMySQL MySQL Connectivity
checkMongoDB MongoDB Connectivity
checkMessageMQ Message Queue Connectivity
checkHostedConnector Hosted Connector Connectivity
checkQueryPreview Query Preview
checkQuerySaveAndRunNow Query Save and Run Now
checkDashboardLoad Dashboard Load
checkWidgetLoad Widget Load
Response
HTTP Status Response
200 OK Lists components and their subcomponents. Components are represented by JSON objects. Output example: 
{
    'name': 'MongoDB Connectivity',
    'status': 'RED',
    'time': 0,
    'comment': 'Timed out after 30000 ms while waiting to connect. Client view of cluster state is {type=UNKNOWN, servers=[{address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}]',
    'statusLevel': 2
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Missed groupName field
  • Failed to edit group - details saved at server log
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to access KPI
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X GET http://localhost:9090/api/1.0/kpi/checkMongoDB

 

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles