What can we help you with?

e.g. Getting Started, Build Dashboards

Top

Widget Management

Follow

List Widgets

Query
GET /api/1.0/widgets?byCategory=<byCategory>
Parameter Comments
byCategory Query parameter, optional. If set, then widgets filtered by specified category
Response
HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "id":25901,
         "name":"test5",
         "userId":10077,
         "customerId":1033,
         "datasetId":15150,
         "type":2,
         "description":null,
         "urlString":"02SscJ",
         "access":0,
         "refreshChartMillis":-1,
         "createdDate":1492282355000,
         "jsonConfig":null,
         "queryId":-1,
         "queryStr":null,
         "adhocQuery":null,
         "category":"All",
         "drilldown":false,
         "dataset":{
            "createdDate":1492282355000,
            "lastModDate":1492282355000,
            "id":15150,
            "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
            "mongoId":null,
            "mongoConnectUri":"localhost:27017/Some_a3PNFK",
            "customerId":1033,
            "datasetName":"test5",
            "identifier":null,
            "userId":0,
            "customer":null,
            "metaData":{
               "fieldNames":[
                  "id_0",
                  "id",
                  "geometry",
                  "properties"
               ],
               "dataTypes":{
                  "id_0":"java.lang.String",
                  "id":"java.lang.String",
                  "geometry":"java.util.Map",
                  "properties":"java.util.Map"
               }
            }
         },
         "position":{
            "chartId":25901,
            "width":-1,
            "height":-1,
            "originalScreenWidth":-1,
            "originalScreenHeight":-1,
            "col":1,
            "row":13,
            "id":25901,
            "xpos":0,
            "ypos":0,
            "size_x":12,
            "size_y":12
         },
         "associations":null,
         "queryModified":false,
         "updateFilters":false,
         "dataFields":[

         ],
         "transientChartFilters":null,
         "typeModified":false,
         "lastSyncDate":1492282355000,
         "viewOnly":false,
         "truncated":false,
         "processedName":"test5",
         "widgetConfig":null,
         "chartProperties":{
            "chart.type":"datagrid"
         },
         "statusIndColumns":[

         ],
         "gridBean":null,
         "dataRow":null,
         "text":"",
         "colNames":null,
         "dataRows":null,
         "live":false,
         "filters":null,
         "widgetType":"DATA_GRID",
         "macros":null,
         "strictFilters":null,
         "dbFields":[

         ],
         "widgetTypeStr":"datagrid",
         "filterFieldDataTypes":{
            "geometry":"java.util.Map",
            "id":"java.lang.String",
            "id_0":"java.lang.String",
            "properties":"java.util.Map"
         },
         "allFilters":[

         ],
         "processedFilters":[

         ]
      }
   ]
}
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 -H "Authorization: Bearer HERE_IS_YOUR_BEARER" https://www.knowi.com/api/1.0/widgets/

 

List Widget Alerts

Query

GET /api/1.0/widgets/<objectId>/alerts

Parameter Comments
objectId Widget id to list alerts in it
Response
HTTP Status Response
200 OK Output example: 
{
  "list": [
    {
      "createdDate": 1648134840000,
      "lastModDate": 1648134840000,
      "id": 242,
      "datasetId": 16170,
      "lastAlert": null,
      "sendToOld": null,
      "userId": 10077,
      "alertCondition": "select * where Sent > 100",
      "dataset": null,
      "alertName": "alert12",
      "alertType": 4,
      "lastDataMeta": null,
      "accessLevel": 1,
      "scheduleId": 105,
      "schedule": {
        "frequencyType": "minute",
        "frequency": 15,
        "startTime": null,
        "cronConfig": "*/15 * * * *",
        "id": 105,
        "type": 0,
        "host": null,
        "createdDate": 1648134840000,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 1648124040,
        "nextExecutionTime": 1648124040000
      },
      "realtime": true,
      "executionReport": null,
      "firedCount": 0,
      "createdBy": null,
      "deletable": false,
      "chartId": 26908,
      "lastDataMetaObj": null,
      "properties": {
        "classVersion": 2,
        "emailOutput": {
          "classVersion": 1,
          "from": "support@knowi.com",
          "sendTo": "Some@some.com",
          "cc": "",
          "bcc": "",
          "emailSubject": "alert10",
          "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
          "attachDataset": false,
          "attachResultsAfterCloud9ql": false
        },
        "webhookOutput": {
          "classVersion": 1,
          "selectedWebhooks": [
            200
          ]
        },
        "attachAdditionalResults": false,
        "additionalResults": {
          "additionalDatasetId": null,
          "additionalQuery": ""
        },
        "generateAlertIfNoDataDetected": false,
        "skipAlertIfDataOrLastUpdateSameAsBefore": true,
        "attachConditionalData": true,
        "frequencyMarker": "custom",
        "operator": ">",
        "metric": "Sent",
        "threshold": "100"
      }
    },
    {
      "createdDate": 1648121285000,
      "lastModDate": 1648121285000,
      "id": 240,
      "datasetId": 16170,
      "lastAlert": null,
      "sendToOld": null,
      "userId": 10077,
      "alertCondition": "select * where Sent > 100",
      "dataset": null,
      "alertName": "alert12",
      "alertType": 4,
      "lastDataMeta": null,
      "accessLevel": 1,
      "scheduleId": 103,
      "schedule": {
        "frequencyType": "minute",
        "frequency": 15,
        "startTime": null,
        "cronConfig": "*/15 * * * *",
        "id": 103,
        "type": 0,
        "host": null,
        "createdDate": 1648121285000,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 1648110485,
        "nextExecutionTime": 1648110485000
      },
      "realtime": true,
      "executionReport": null,
      "firedCount": 0,
      "createdBy": null,
      "deletable": false,
      "chartId": 26908,
      "lastDataMetaObj": null,
      "properties": {
        "classVersion": 2,
        "emailOutput": {
          "classVersion": 1,
          "from": "support@knowi.com",
          "sendTo": "Some@some.com",
          "cc": "",
          "bcc": "",
          "emailSubject": "alert10",
          "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
          "attachDataset": false,
          "attachResultsAfterCloud9ql": false
        },
        "webhookOutput": {
          "classVersion": 1,
          "selectedWebhooks": [
            200
          ]
        },
        "attachAdditionalResults": false,
        "additionalResults": {
          "additionalDatasetId": null,
          "additionalQuery": ""
        },
        "generateAlertIfNoDataDetected": false,
        "skipAlertIfDataOrLastUpdateSameAsBefore": true,
        "attachConditionalData": true,
        "frequencyMarker": "custom",
        "operator": ">",
        "metric": "Sent",
        "threshold": "100"
      }
    }
  ]
}
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 the alerts
  • Current user is not allowed to access specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26908/alerts

 

Get Widget Details by Id

Query
GET /api/1.0/widgets/<objectId>
Parameter Comments
objectId Widget id to view
Response
HTTP Status Response
200 OK Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
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 widget

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" https://www.knowi.com/api/1.0/widgets/10001

Get Widget Share Url

POST /api/1.0/widgets/<objectId>/share/url

Parameter Comments
objectId Widget id to generate share url
contentFilters Optional form parameter content filters
Response
HTTP Status Response
200 OK Output example: 
{
 "shareUrl": "Zar1OtKVb7iiiiV6Ufa8VJ25Wo3jvrPI1aySdisvceplMEie?contentFilters=%5B%7B%22fieldName%22%3A%22Customer%22%2C%22values%22%3A%5B%22Facebook%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D"
}

Note: To construct the full url, prepend /w/ and the “shareUrl” to the host name and port. For example: http://localhost:9090/w/Zar1OtKVb7iiiiV6UfI1aySdisvceplMEie?contentFilters=%5B%7B%22fieldName%22%3A%22Customer%22%2C%22values%Facebook%22%5D%2C%22operator%22%3A%22
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:
  • Current user is not allowed to generate widget share url
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 generate widget share url
Example

curl -X POST -i http://localhost:9090/api/1.0/widgets/3528/share/url -H 'Authorization: Bearer HERE_IS_YOUR_BEARER' -H 'Content-Type: application/x-www-form-urlencoded' -d 'contentFilters=[{"fieldName":"Customer","values":["Facebook"],"operator":"="}]'

Get Widget Secure Share Url

POST /api/1.0/widgets/<objectId>/share/url/secure

Parameter Comments
objectId Widget id to generate secure share url
contentFilters Optional form parameter content filters
Response
HTTP Status Response
200 OK Output example: 
{
 "secureShareUrl": "S0jBEWZ2WLNCCe8pXQYtTbip3zrq3oaM8iplCQDzEhpEkie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww=="
}

Note: To construct the full url, prepend /w-secure/ and the “secureShareUrl” to the host name and port. For example: http://localhost:9090/w-secure/S0jBEWZ2WLNCCe8pXQYtTbip3zrq3oaM8iplCQDzEhpEkie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww==
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Customer token is missing, can't encrypt content filters
  • Error details:
  • Current user is not allowed to generate widget secure share url
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 generate widget secure share url
Example

curl -X POST -i http://localhost:9090/api/1.0/widgets/3528/share/url/secure -H 'Authorization: Bearer HERE_IS_YOUR_BEARER' -H 'Content-Type: application/x-www-form-urlencoded' -d 'contentFilters=[{"fieldName":"Customer","values":["Facebook"],"operator":"="}]'

 

Get Widget Dataset Query Mapper

Get info where from the widget is created, like in UI the Data Diagram for Widget. The output field queries at position [0] will be the source query used for widget creation.

Query

GET /api/1.0/widgets/<objectId>/alerts

Parameter Comments
objectId Widget id from which to get query mapper
Response
HTTP Status Response
200 OK Output example: 
{
  "datasetId": 15848,
  "datasetName": "sendingActivity2019-06-18-11-19",
  "datasetMetadata": {
    "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.String"
      },
      {
        "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.String",
      "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"
    ]
  },
  "queries": [
    {
      "op": 0,
      "connectorSyncStatus": 0,
      "id": 2432,
      "entityName": "sendingActivity2019-06-18-11-19",
      "datasourceId": 0,
      "userId": 0,
      "customerId": 0,
      "status": 0,
      "triggerDatasetId": 0,
      "modelId": 0,
      "accessLevel": 1,
      "categoryAccessLevel": -1,
      "autoShared": false,
      "scheduled": false,
      "direct": false,
      "directPush": false,
      "cacheDuration": 0,
      "datasetId": 0,
      "c9ExportDataset": 0,
      "my": false,
      "drafted": false,
      "triggered": false
    }
  ],
  "widgets": [
    {
      "createdDate": null,
      "lastModDate": null,
      "id": 26560,
      "name": "sendingActivity2019-06-18-11-19b",
      "userId": 0,
      "customerId": 0,
      "datasetId": 0,
      "type": 1,
      "description": null,
      "urlString": null,
      "access": 0,
      "refreshChartMillis": -1,
      "jsonConfig": null,
      "shareUrl": null,
      "accessLevel": 1,
      "dashboardAccessLevel": -1,
      "categoryAccessLevel": -1,
      "autoShared": false,
      "urlShareWhitelistDomain": null,
      "filterSettings": null,
      "chartType": null,
      "alertCount": 0,
      "queryId": -1,
      "queryStr": null,
      "adhocQuery": null,
      "categories": null,
      "userExternalAuthId": 0,
      "userSso": false,
      "drilldown": false,
      "dataset": null,
      "position": {
        "chartId": 0,
        "width": 500,
        "height": 400,
        "originalScreenWidth": 0,
        "originalScreenHeight": 0,
        "col": 0,
        "row": 0,
        "ypos": 0,
        "xpos": 0,
        "id": 0,
        "size_x": 0,
        "size_y": 0
      },
      "associations": null,
      "queryModified": false,
      "updateFilters": false,
      "dataFields": [],
      "dataFieldsTypes": {},
      "transientChartFilters": null,
      "typeModified": false,
      "lastSyncDate": null,
      "viewOnly": false,
      "truncated": null,
      "processedName": "sendingActivity2019-06-18-11-19b",
      "processedDescription": null,
      "processedFootNote": null,
      "error": null,
      "widgetConfig": null,
      "notDefaultFilter": false,
      "chartProperties": {
        "pivot.fitWidgetWidth": "false",
        "pivot.footer": "false",
        "pivot.singleRow": "false",
        "formatOptions": "{\"clicks\":[{\"mode\":\"number\",\"decimal\":\"2\",\"separator\":true}],\"opened\":[{\"mode\":\"number\",\"decimal\":\"\",\"separator\":true}],\"week\":[{\"mode\":\"date\",\"dateformat\":\"mm.dd.yyyy\"}]}",
        "chart.type": "pivot",
        "pivot.sort": "{\"id\":\"12/04/2014 11:00:00 MSK_'_12/10/2014 11:00:00 MSK_'_min_'_conversions\",\"dir\":\"desc\"}",
        "pivot.columnsSortOrder": "desc",
        "pivot.columnWidths": "{\"name\":270.25}",
        "pivot.config.access.viewers": "false",
        "pivot.autoCollapseRows": "false",
        "pivot.totalColumn": "false",
        "chart.quickpickers": "0",
        "pivot.structure": "{\"rows\":[\"customer\",\"message_type\"],\"columns\":[\"week\",\"date\"],\"values\":[{\"name\":\"clicks\",\"text\":\"clicks\",\"id\":1563138446510,\"operation\":[\"sum\"]},{\"name\":\"conversions\",\"text\":\"conversions\",\"id\":1563138446511,\"operation\":[\"min\"]}],\"filters\":[],\"columnSort\":{\"$default\":{\"dir\":\"desc\",\"_dir\":-1},\"week\":{\"dir\":\"desc\",\"_dir\":-1},\"date\":{\"dir\":\"desc\",\"_dir\":-1}}}"
      },
      "filters": [],
      "widgetAccessLevel": 1,
      "chartPropertiesNullOrEmpty": false,
      "filterFieldDataTypes": {},
      "processedFilters": [],
      "live": false,
      "strictFilters": null,
      "dataDisplayTypes": {},
      "dbFields": [],
      "ignoreVals": [],
      "widgetTypeStr": "chart",
      "filterFieldDataTypesIncludingNested": {},
      "gridBean": null
    },
    {
      "createdDate": null,
      "lastModDate": null,
      "id": 26559,
      "name": "sendingActivity2019-06-18-11-19 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
      "userId": 0,
      "customerId": 0,
      "datasetId": 0,
      "type": 1,
      "description": null,
      "urlString": null,
      "access": 0,
      "refreshChartMillis": -1,
      "jsonConfig": null,
      "shareUrl": null,
      "accessLevel": 1,
      "dashboardAccessLevel": -1,
      "categoryAccessLevel": -1,
      "autoShared": false,
      "urlShareWhitelistDomain": null,
      "filterSettings": null,
      "chartType": null,
      "alertCount": 0,
      "queryId": -1,
      "queryStr": null,
      "adhocQuery": null,
      "categories": null,
      "userExternalAuthId": 0,
      "userSso": false,
      "drilldown": false,
      "dataset": null,
      "position": {
        "chartId": 0,
        "width": 500,
        "height": 400,
        "originalScreenWidth": 0,
        "originalScreenHeight": 0,
        "col": 0,
        "row": 0,
        "ypos": 0,
        "xpos": 0,
        "id": 0,
        "size_x": 0,
        "size_y": 0
      },
      "associations": null,
      "queryModified": false,
      "updateFilters": false,
      "dataFields": [],
      "dataFieldsTypes": {},
      "transientChartFilters": null,
      "typeModified": false,
      "lastSyncDate": null,
      "viewOnly": false,
      "truncated": null,
      "processedName": "sendingActivity2019-06-18-11-19 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
      "processedDescription": null,
      "processedFootNote": "foot2 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
      "error": null,
      "widgetConfig": null,
      "notDefaultFilter": false,
      "chartProperties": {
        "chart.historical_y_axis": "clicks",
        "chart.band_x_axis": "date",
        "widget.footnote": "foot2 $c9_DataLastUpdate_${date|yyyy-MM-dd'T'HH:mm:ss}$",
        "chart.type": "band",
        "pivot.columnWidths": "{\"name\":296.75}",
        "pivot.sort": "{\"id\":\"name\",\"dir\":\"asc\"}",
        "chartColor": "#89D4F5:clicks,#BCD759:spam,#FFBF00,#9961A7,#4891EA,#EE965B,#F284D1,#6FDBCB,#2D71C4,#EF5A5A,#609C29,#C69B06,#8A2299,#996D6C,#2F2F6C,#1C6C61",
        "prevWidgetType": "bubble",
        "chart.quickpickers": "0",
        "pivot.structure": "{\"rows\":[\"customer\",\"message_type\",\"campaign_name\"],\"columns\":[\"week\",\"date\"],\"values\":[{\"name\":\"clicks\",\"text\":\"clicks\",\"id\":1560849374643,\"operation\":[\"sum\"]},{\"name\":\"spam\",\"text\":\"spam\",\"id\":1560849374644,\"operation\":[\"sum\"]}],\"filters\":[{\"name\":\"campaign_name\",\"text\":\"campaign_name\",\"type\":\"select\",\"id\":1560849374645}],\"columnSort\":{\"$default\":{\"dir\":\"asc\",\"_dir\":1},\"date\":{\"dir\":\"asc\",\"_dir\":1},\"week\":{\"dir\":\"asc\",\"_dir\":1}}}",
        "d3.sankey.array": "[{\"from\":\"week\",\"to\":\"clicks\",\"value\":\"spam\"},{\"from\":\"customer\",\"to\":\"date\",\"value\":\"campaign_name\"}]"
      },
      "filters": [],
      "widgetAccessLevel": 1,
      "chartPropertiesNullOrEmpty": false,
      "filterFieldDataTypes": {},
      "processedFilters": [],
      "live": false,
      "strictFilters": null,
      "dataDisplayTypes": {},
      "dbFields": [],
      "ignoreVals": [
        "date",
        "campaign_name",
        "week",
        "clicks",
        "message_type",
        "spam",
        "message_type2",
        "customer"
      ],
      "widgetTypeStr": "chart",
      "filterFieldDataTypesIncludingNested": {},
      "gridBean": null
    }
  ],
  "derivedQueries": [],
  "sourceDatasets": []
}
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 widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26559/mapper

 

Reset User Filters to Default for Widget

Remove user filters and set default filters.

Query

GET /api/1.0/widgets/<objectId>/filter/reset

Parameter Comments
objectId Widget id in which to reset user filters to defaault filters
Response
HTTP Status Response
200 OK Output example: Output Widget entity with updated filters
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 edit specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26559/filter/reset

Update Default Filters for Widget

Query

PUT /api/1.0/widgets/<objectId>/filter/default

Parameter Comments
objectId Widget id in which to update default filters

PUT JSON payload:

 
To get all varity of input parameters, please create filter in UI first, and then get/list it with another endpoint to investigate possible inputs. It may be changed in future versions.
Example: 
      {"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}
Response
HTTP Status Response
200 OK Output the widget with updated default filters>
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 Filters field
  • Wrong Filters field
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 edit specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}'  http://localhost:9090/api/1.0/widgets/26559/filter/default

Reset user filters to Default for Widget

Remove user filters and set default filters.

Query

GET /api/1.0/widgets/<objectId>/filter/reset

Parameter Comments
objectId Widget id in which to reset user filters to defaault filters
Response
HTTP Status Response
200 OK Output example: Output Widget entity with updated filters
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 edit specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26559/filter/reset

Update Default Filters for Widget

Query

PUT /api/1.0/widgets/<objectId>/filter/default

Parameter Comments
objectId Widget id in which to update default filters

PUT JSON payload:

 
To get all varity of input parameters, please create filter in UI first, and then get/list it with another endpoint to investigate possible inputs. It may be changed in future versions.
Example: 
      {"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}
Response
HTTP Status Response
200 OK Output the widget with updated default filters>
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 Filters field
  • Wrong Filters field
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 edit specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}'  http://localhost:9090/api/1.0/widgets/26559/filter/default

Create Widget

Query
POST /api/1.0/widgets/

POST JSON payload:

Parameter Comments
datasetId Id of Dataset to use to create Widget
widgetName Widget name
Response
HTTP Status Response
200 OK Return created Widget json info (same as "Get widget" command). Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
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 datasetId field
  • Missed widgetName field
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 add widget using specified dataset
  • Have no permissions to add new widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d "{\"datasetId\":15134,\"widgetName\":\"newWidgetName1\"}" https://www.knowi.com/api/1.0/widgets

Delete Widget

Query
DELETE /api/1.0/widgets/<objectId>
Parameter Comments
objectId Widget id to delete
Response
HTTP Status Response
200 OK No response body
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 delete specified widget

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE https://www.knowi.com/api/1.0/widgets/25902

Edit Widget

Query

PUT /api/1.0/widgets/<objectId>

Parameter Comments
objectId Widget id of Widget to edit

PUT JSON payload:

Parameter Comments
widgetName Optional string. Widget name
widgetType Optional integer. Widget type. It is works togeter with "chart.type" parameter inside chartProperties to set actual chart kind.
chartProperties Optional string. JSON with all chart properties. To get an example of this JSON you can get example of your chart properties from your existing widget (using Get Widget Details command), which contains chartProperties field.
filters Optional JSON array with filters to set to widget
Response
HTTP Status Response
200 OK Return edited Widget json info (same as "Get Widget" command). Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
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:
  • Wrong chartProperties format
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 edit specified widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.
Example 1
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"widgetName\":\"updatedWidgetName1\"}"  http://localhost:9090/api/1.0/widgets/123
Example 2
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"chartProperties\":{\"chart.type\":\"datagrid2\",\"font.size\":\"25\",\"grid.resetColumnWidth\":\"false\",\"grid.collapsible\":\"false\",\"chart.quickpickers\":\"0\"}}"  http://localhost:9090/api/1.0/widgets/123
Example 3 (Possible to set filters)

curl -i -H "Authorization: Bearer HEREISYOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"filters":[{"fieldName":"Bounced","values":["8888"],"operator":"Equals","type":"java.lang.Integer","enabled":true,"visible":true,"transientFilter":false,"fieldType":"java.lang.Integer"}]}' http://localhost:9090/api/1.0/widgets/26908


Clone Widget

Query
POST /api/1.0/widgets/<objectIdToClone>
Parameter Comments
objectIdToClone Widget id of Widget to clone

POST JSON payload:

Parameter Comments
widgetName New (cloned) Name of Widget
Response
HTTP Status Response
200 OK Return cloned Widget json info (same as "Get Widget" command). Output example: 
{
 "id":25901,
 "name":"test5",
 "userId":10077,
 "customerId":1033,
 "datasetId":15150,
 "type":2,
 "description":null,
 "urlString":"02SscJ",
 "access":0,
 "refreshChartMillis":-1,
 "createdDate":1492282355000,
 "jsonConfig":null,
 "queryId":-1,
 "queryStr":null,
 "adhocQuery":null,
 "category":"All",
 "drilldown":false,
 "dataset":{
    "createdDate":1492282355000,
    "lastModDate":1492282355000,
    "id":15150,
    "metadataConfig":"{\"fieldNames\":[\"id_0\",\"id\",\"geometry\",\"properties\"],\"dataTypes\":{\"id_0\":\"java.lang.String\",\"id\":\"java.lang.String\",\"geometry\":\"java.util.Map\",\"properties\":\"java.util.Map\"}}",
    "mongoId":null,
    "mongoConnectUri":"localhost:27017/Some_a3PNFK",
    "customerId":1033,
    "datasetName":"test5",
    "identifier":null,
    "userId":0,
    "customer":null,
    "metaData":{
       "fieldNames":[
          "id_0",
          "id",
          "geometry",
          "properties"
       ],
       "dataTypes":{
          "id_0":"java.lang.String",
          "id":"java.lang.String",
          "geometry":"java.util.Map",
          "properties":"java.util.Map"
       }
    }
 },
 "position":{
    "chartId":25901,
    "width":-1,
    "height":-1,
    "originalScreenWidth":-1,
    "originalScreenHeight":-1,
    "col":1,
    "row":13,
    "id":25901,
    "xpos":0,
    "ypos":0,
    "size_x":12,
    "size_y":12
 },
 "associations":null,
 "queryModified":false,
 "updateFilters":false,
 "dataFields":[

 ],
 "transientChartFilters":null,
 "typeModified":false,
 "lastSyncDate":1492282355000,
 "viewOnly":false,
 "truncated":false,
 "processedName":"test5",
 "widgetConfig":null,
 "chartProperties":{
    "chart.type":"datagrid"
 },
 "statusIndColumns":[

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "strictFilters":null,
 "dbFields":[

 ],
 "widgetTypeStr":"datagrid",
 "filterFieldDataTypes":{
    "geometry":"java.util.Map",
    "id":"java.lang.String",
    "id_0":"java.lang.String",
    "properties":"java.util.Map"
 },
 "allFilters":[

 ],
 "processedFilters":[

 ]
}
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 widgetName field
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 clone specified widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.

Example

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d "{\"widgetName\":\"clonedWidgetName1\"}" https://www.knowi.com/api/1.0/widgets/12345

Share Widget to Users/Groups

Query
PUT /api/1.0/widgets/<objectId>/share
Parameter Comments
objectId Widget Id to share
sso_user Optional bool. Set to `true` if sharing to sso user

PUT JSON payload:

Parameter Comments
shareProperties Share properties json array. Available fields:
  • Type: Users, Groups.
  • access_level: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "access_level" : 1, 
    "name" : "someUser1@host.com" 
  },
  { 
    "type" : "Groups", 
    "access_level" : 1, 
    "id" : 10001 
  } 
]
Response
HTTP Status Response
200 OK  No response body
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 shareProperties field
  • shareProperties missed the type field
  • shareProperties missed the access_level field
  • shareProperties has invalid the type value
  • shareProperties has invalid the access_level value
  • shareProperties missed the id field
  • shareProperties missed the name field
  • shareProperties has invalid the name field
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 share specified widget
415 UNSUPPORTED_MEDIA_TYPE Cannot consume content type - The server refused this request because the request entity is in a format not supported by the requested resource for the requested method.
Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles