What can we help you with?

e.g. Getting Started, Build Dashboards

Top

Dashboard Management

Follow

List Dashboards

This endpoint returns a listing of all the dashboards
GET /api/1.0/dashboards
Parameter Comments
byCategory Optional parameter. Comma separated list of categories IDs to filter by. Multiple categories applied as OR operator.
Response
HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "createdDate":1484118380000,
         "id":110634,
         "name":"Dashboard1",
         "userId":10077,
         "url":"eD8yPisWdcQhdOeip2IJii6Tip1dLNOlFJiiDHhW3iiqSHqtQie",
         "selected":true,
         "displayOrder":0,
         "screenAdjust":true,
         "screenWidth":1447,
         "screenHeight":908,
         "lastModDt":1492849740000,
         "lastAccessDt":1492849740000,
         "locked":false,
         "accessLevel":1,
         "showWidgetList":true
      },
      {
         "createdDate":1481572146000,
         "id":110617,
         "name":"Dashboard2",
         "userId":10077,
         "url":"m2a68Ahq9l9cNWKNQoqXipiirjzwiiUGPUis0QurjbHE5bIie",
         "selected":true,
         "displayOrder":0,
         "screenAdjust":false,
         "screenWidth":1680,
         "screenHeight":1050,
         "lastModDt":1492550129000,
         "lastAccessDt":1492550093000,
         "locked":false,
         "accessLevel":1,
         "showWidgetList":true,
      }
   ]
}
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/dashboards?byCategory=124,5235 

 

Get Dashboard Details

This endpoint returns the filter details, default filters of the dashboard of a given object id

GET /api/1.0/dashboards/<objectId>

Parameter Comments
objectId Dashboard id to view Dashboard
Response
HTTP Status Response
200 OK

JSON object with list of users and groups with whom the dashboard has been shared.

Note: If a dashboard hasn't been shared with any user or group, an endpoint will return an empty list.

Output example:

{
  "createdDate": 1648068871000,
  "id": 111096,
  "name": "dash143",
  "userId": 10077,
  "url": "HVa5lnnSTripXot5n4jrzUq4j4cjnr7Iisb1gffTwBxwUie",
  "selected": true,
  "displayOrder": 0,
  "screenAdjust": true,
  "screenWidth": 1515,
  "screenHeight": 0,
  "lastModDt": 1648659658000,
  "lastAccessDt": 1648659606000,
  "locked": false,
  "accessLevel": 0,
  "categoryAccessLevel": -1,
  "autoShared": false,
  "favorite": false,
  "notDefaultFilter": true,
  "properties": {
    "excludeGridWidgetsFromPdfExport": false,
    "excludeExpandedGridFromPdfExport": false,
    "filters": [
      {
        "fieldName": "Clicks",
        "values": [
          "1005"
        ],
        "operator": "Greater than",
        "type": "java.lang.Integer",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "dashboardDisplayValues": [
          "1005"
        ],
        "fieldType": "java.lang.Integer",
        "label": "Filter Label",
        "description": "Filter Description"
      }
    ],
    "defaultFilters": [
      {
        "fieldName": "Clicks",
        "values": [
          "1000"
        ],
        "operator": "Greater than",
        "type": "java.lang.Integer",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "dashboardDisplayValues": [
          "1000"
        ],
        "fieldType": "java.lang.Integer"
      }
    ]
  },
  "my": false,
  "orderedPositions": [
    {
      "chartId": 26908,
      "width": 500,
      "height": 400,
      "originalScreenWidth": 0,
      "originalScreenHeight": 0,
      "col": 1,
      "row": 1,
      "ypos": 0,
      "xpos": 0,
      "id": 26908,
      "size_x": 12,
      "size_y": 12
    },
    {
      "chartId": 26909,
      "width": 500,
      "height": 400,
      "originalScreenWidth": 0,
      "originalScreenHeight": 0,
      "col": 13,
      "row": 1,
      "ypos": 0,
      "xpos": 0,
      "id": 26909,
      "size_x": 12,
      "size_y": 12
    }
  ],
  "showWidgetList": true,
  "dashNameAsValidFilename": "dash143"
}
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 dashboard

Example

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

 

Generate Dashboard Share Url

This endpoint is for generating a dashboard share URL

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

Parameter Comments
objectId Dashboard id to update share url
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the dashboard, which allows using of the same dashboard as a kind of template and generates different PDF exported report files with a different set of filters. It is optional (can be skipped or set to empty string)

Example:

[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
refresh

true (Default)

If false and the current dashboard already has share URLs, the endpoint will NOT update the existing hash.  Instead, it will just generate the content filter hash.  The response is the same as before (i.e. unchanged).

Note- when the refresh flag is set to false and the dashboard does NOT have a share or secure share (respectively) enabled, the endpoint will try to enable it.
HTTP Status Response
200 OK Output example: 
{
 "shareUrl": "4PdpqevhrfPYzXcAbmxWJhtip38VmrQie?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 /d/ and the “shareUrl” to the host name and port. For example: http://localhost:9090/d/4PdpqevhrfPYxmof638VmrQie?contentFilters=%7B%22fieldName%222Customer%22%2C%22values%22%3A%5B%22Facebook%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:
  • Current user is not allowed to generate dashboard 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 dashboard share url
 

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

 

Generate Dashboard Secure Share Url

This endpoint is for generating a dashboard secure share URL of a given dashboard id

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

Parameter Comments
objectId Dashboard id to generate share url
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the dashboard, which allows using of the same dashboard as a kind of template and generates different PDF exported report files with a different set of filters. It is optional (can be skipped or set to empty string)

Example:

[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
refresh

true (Default)

If false and the current dashboard already has share URLs, the endpoint will NOT update the existing hash.  Instead, it will just generate the content filter hash.  The response is the same as before (i.e. unchanged).

Note- when the refresh flag is set to false and the dashboard does NOT have a share or secure share (respectively) enabled, the endpoint will try to enable it.
HTTP Status Response
200 OK Output example: 
{
 "secureShareUrl": "kN3Gj9jipB458gipMJ8EoaeC8rWfn8V9PQie/dnqPwU7UB1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww=="
}

Note: To construct the full url, prepend /share/secure/ and the secureShareUrl to the host name and port. For example: http://localhost:9090/share/secure/kN3Gj9j8rWfny3kp2XIPamz8V9PQie/dnqPwU7UF61jmT+rgIft4aE9PnDoJlcSiov6CIWd___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
  • Current user is not allowed to generate dashboard 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 dashboard share url
 

  curl -X POST -i http://localhost:9090/api/1.0/dashboards/110865/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":"="}]'

 

Create Dashboard Secure Share Hash

This endpoint is for creating a hash for embedding a secure URL of a given set of filters. Whereas the API call above will regenerate the full secure URL, this call will only generate the hash while leaving the share URL id the same.

POST/api/1.0/dashboards/<objectId>/share/url/secure/hash

Parameter Comments
objectId Dashboard id to generate share url
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the dashboard, which allows using of the same dashboard as a kind of template and generates different PDF exported report files with a different set of filters. It is optional (can be skipped or set to empty string)

Example:

[{"fieldName":"$c9_<field>$", "type": "java.lang.String", "values":["33"], "operator": "Equals"}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
HTTP Status Response
200 OK Output example: 
{
 "secureHash": "kN3Gj9jipB458gipMJ8EoaeC8rWfn8V9PQie/dnqPwU7UB1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww=="
}

Note: To construct the full url, prepend /share/secure/ and the secureHash to the host name and port. For example: http://localhost:9090/share/secure/kN3Gj9j8rWfny3kp2XIPamz8V9PQie/dnqPwU7UF61jmT+rgIft4aE9PnDoJlcSiov6CIWd___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
  • Current user is not allowed to generate dashboard 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 dashboard share url
 

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

 

Share Dashboard to Users/Groups

This endpoint is for sharing the dashboard with users or groups of a given dashboard id
PUT /api/1.0/dashboards/<objectId>/share
Parameter Comments
objectId Dashboard id of Dashboard 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 dashboard
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 PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"access_level\" : 1, \"name\" : \"someUser@host.com\" } ] }" https://www.knowi.com/api/1.0/dashboards/110643/share

 

Create Dashboard

This endpoint is for creating a new dashboard
POST /api/1.0/dashboards/

POST JSON payload:

Parameter Comments
dashName Dashboard name
screenWidth Dashboard screen width in pixels
screenHeight Dashboard screen height in pixels

Response

HTTP Status Response
200 OK Return created Dashboard json info (same as "Get Dashboard" command). Output example: 
{
 "createdDate":1481572146000,
 "id":110617,
 "name":"Dashboard2",
 "userId":10077,
 "url":"m2a68Ahq9l9cNWKNQoqXipiirjzwiiUGPUis0QurjbHE5bIie",
 "selected":true,
 "displayOrder":0,
 "screenAdjust":false,
 "screenWidth":1680,
 "screenHeight":1050,
 "lastModDt":1492550129000,
 "lastAccessDt":1492550093000,
 "locked":false,
 "accessLevel":1,
 "showWidgetList":true,
}
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 dashName field
  • Invalid screenWidth field
  • Invalid screenHeight field
  • Invalid group specified
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
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 "{\"dashName\":\"dashboardName1\",\"screenWidth\":1000,\"screenHeight\":800}" https://www.knowi.com/api/1.0/dashboards

 

Delete Dashboard

This endpoint is for deleting a dashboard of given dashbaord id
Query
DELETE /api/1.0/dashboards/<objectId>
Parameter Comments
objectId Id of Dashboard 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
  • Error details:
  • Error removing dashboard - more details 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 delete specified dashboard


Example

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

 

Edit Dashboard

This endpoint is for updating/modifying a dashboard of a given dashboard id
Query
PUT /api/1.0/dashboards/<objectId>
Parameter Comments
objectId Dashboard id of Dashboard to edit


PUT JSON payload:

Parameter Comments
dashName New name of Dashboard
categories 

Name of categories. 

for example: "categories: [".."]

Response
HTTP Status Response
200 OK Return edited Dashboard json info (same as "Get Dashboard" command). Output example: 
{
 "createdDate":1481572146000,
 "id":110617,
 "name":"Dashboard2",
 "userId":10077,
 "url":"m2a68Ahq9l9cNWKNQoqXipiirjzwiiUGPUis0QurjbHE5bIie",
 "selected":true,
 "displayOrder":0,
 "screenAdjust":false,
 "screenWidth":1680,
 "screenHeight":1050,
 "lastModDt":1492550129000,
 "lastAccessDt":1492550093000,
 "locked":false,
 "accessLevel":1,
 "showWidgetList":true,
}
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 dashName 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 dashboard
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 PUT -d "{\"dashName\":\"updatedDashboardName1\", \"categories\": [\category_name\"]}" https://www.knowi.com/api/1.0/dashboards/10001 

 

Clone Dashboard

This endpoint is for cloning/copying a dashboard
Query
POST /api/1.0/dashboards/<objectIdToClone>
Parameter Comments
objectIdToClone Dashboard id of Dashboard to clone


POST JSON payload:

Parameter Comments
dashName New (cloned) Name of Dashboard
shouldCloneWidgets Optional boolean parameter to indicate whether to clone the dashboard together with all the widgets on this dashboard.
cloneWidgetsPrefix Optional string parameter to specify a prefix for the cloned widget names.
cloneWidgetsSuffix Optional string parameter to specify a suffix for the cloned widget names.
screenWidth Cloned dashboard screen width in pixels
screenHeight Cloned dashboard screen height in pixels

Response
HTTP Status Response
200 OK Return cloned Dashboard json info (same as "Get Dashboard" command). Output example: 
{
 "createdDate":1481572146000,
 "id":110617,
 "name":"Dashboard2",
 "userId":10077,
 "url":"m2a68Ahq9l9cNWKNQoqXipiirjzwiiUGPUis0QurjbHE5bIie",
 "selected":true,
 "displayOrder":0,
 "screenAdjust":false,
 "screenWidth":1680,
 "screenHeight":1050,
 "lastModDt":1492550129000,
 "lastAccessDt":1492550093000,
 "locked":false,
 "accessLevel":1,
 "showWidgetList":true,
}
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:
  • Error cloning dashboard - no any additional info available
  • Missed dashName field
  • Missed screenWidth field
  • Missed screenHeight 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 dashboard
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 "{\"dashName\":\"clonedDashboardName1\",\"screenWidth\":1000,\"screenHeight\":800}" https://www.knowi.com/api/1.0/dashboards/110643

 

List Widgets in the Dashboard

This endpoint returns a listing all the dashboard widgets
Query
GET /api/1.0/dashboards/<objectId>/widgets?byCategory=<byCategory>
Parameter Comments
objectId Dashboard id in which to get widgets list
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
403 FORBIDDEN 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Current user is not allowed to get widgets of specified dashboard

Example 

curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" https://www.knowi.com/api/1.0/dashboards/10001/widgets?byCategory=124,923

 

Export dashboard to PDF

This endpoint is for exporting the PDF file of a dashboard of a given dashboard id

GET /api/1.0/dashboards/<objectId>/export/pdf?contentFilters={content_filters}

Parameter Comments
objectId Dashboard id to export to PDF
contentFilters

The contentFilter is a JSON array of the field name, value, and operator of filters to be applied to the dashboard, which allows using of the same dashboard as a kind of template and generates different PDF exported report files with a different set of filters.

Optional (could be set to empty string), the content filters set to User. Example:

[{“fieldName”: “page”, “values”:[“Products”], “operator”:“=”}]

Available Operators for Content Filters:

"Greater than" (>), "Greater than or equals" (>=), "Less than" (<), "Less than or equals" (<=), "Not Equals" (!=), "Equals" (=), "Contains", "Does Not Contain", "Range", "like", "not like", "in", "not in", "regexp", "is null", and "is not null"

Note: All operators are applied to all field types, it depends on the field type for which operator they are required and some operators may not be applied.
HTTP Status Response
200 OK Output example: 
Pdf binary content.
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 access specified dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" "http://localhost:9090/api/1.0/dashboards/10001/export/pdf?contentFilters=%5B%7B%22fieldName%22%3A%22page%22%2C%22values%22%3A%5B%22Products%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D" > file1.pdf

 

List user Filter sets

This endpoint returns a listing of all the user filter sets

GET /api/1.0/dashboards/filterset

HTTP Status Response
200 OK Output example: 
[
    {
        "createdDate": null,
        "lastModDate": 1565638416000,
        "id": 102092,
        "userId": 1214,
        "name": "filterset",
        "accessLevel": 1,
        "filters": [
        ]
    }
]
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 list of filter sets
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/dashboards/filterset

 

Update Filters and Filtersets

This endpoint is for updating/modifying the filters and filtersets of a given filter i

PUT /api/1.0/dashboards/<objectId>/filter/update

Parameter Comments
objectId Dashboard id into which to update filters and filtersets

PUT JSON payload:

 
Sample input, the "properties" contains list of filters, the "filterSets" contains list of filterset to set to dashboard: 
        {
  "properties": [
    {
      "fieldName": "Bounced",
      "values": [
        "5566"
      ],
      "operator": "Not Equals",
      "type": "java.lang.Integer",
      "enabled": true,
      "visible": true,
      "transientFilter": false,
      "dashboardDisplayValues": [
        "5566"
      ],
      "fieldType": "java.lang.Integer",
      "sortIndex": 0, 
      "label": "Filter Label",
      "description": "Filter Description"
    }
  ],
  "readOnly": false,
  "filterSets": [
    {
      "accessLevel": 1,
      "name": "fs2",
      "id": 102106,
      "filters": [
        {
          "fieldName": "Conversions",
          "values": [
            "800"
          ],
          "operator": "Not Equals",
          "type": "java.lang.Integer",
          "enabled": true,
          "visible": true,
          "fieldType": "java.lang.Integer",
          "fromFilterSet": true
        }
      ],
      "enabled": true,
      "defaultFilters": false,
      "locked": false,
      "visible": true
    }
  ]
}
 
 
HTTP Status Response
200 OK No content returned.
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:
  • Failed to update dashboard filters
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 a dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"properties":[{"fieldName":"Bounced","values":["5566"],"operator":"Not Equals","type":"java.lang.Integer","enabled":true,"visible":true,"transientFilter":false,"dashboardDisplayValues":["5566"],"fieldType":"java.lang.Integer","sortIndex":0}],"readOnly":false,"filterSets":[{"accessLevel":1,"name":"fs2","id":102106,"filters":[{"fieldName":"Conversions","values":["800"],"operator":"Not Equals","type":"java.lang.Integer","enabled":true,"visible":true,"fieldType":"java.lang.Integer","fromFilterSet":true}],"enabled":true,"defaultFilters":false,"locked":false,"visible":true}]}' http://localhost:9090/api/1.0/dashboards/111064/filter/update

 

Update Default Filters for Dashboard

This endpoint will clean up user filters and FilterSets on the dashboard and set default filters and filterSets. The filters will be set from input JSON, the FilterSet will be set from current user filtersets from a dashboard.

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

Parameter Comments
objectId Dashboard id in which set default filters

PUT JSON payload:

 
The "properties" contains list of filters.

Sample: 
{
  "properties": [
    {
      "fieldName": "Bounced",
      "values": [
        "5566"
      ],
      "operator": "Not Equals",
      "type": "java.lang.Integer",
      "enabled": true,
      "visible": true,
      "transientFilter": false,
      "dashboardDisplayValues": [
        "5566"
      ],
      "fieldType": "java.lang.Integer",
      "sortIndex": 0, 
      "label": "Filter Label",
      "description": "Filter Description"
    }
  ]
}
HTTP Status Response
200 OK No content returned.
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:
  • Failed to update dashboard filters
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 a dashboard"
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"properties":[{"fieldName":"Bounced","values":["5566"],"operator":"Not Equals","type":"java.lang.Integer","enabled":true,"visible":true,"transientFilter":false,"dashboardDisplayValues":["5566"],"fieldType":"java.lang.Integer"}]}' http://localhost:9090/api/1.0/dashboards/111097/filter/default

 

Reset User Filters to Default for Dashboard

This endpoint is for resetting the user filter to the default dashboard of a given filterset id

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

Parameter Comments
objectId Dashboard id in which reset user filters to default filters
HTTP Status Response
200 OK No content returned
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 a dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/dashboards/111064/filter/reset

 

Create Filter Set

This endpoint is for creating a new filter set

POST /api/1.0/dashboards/filterset

No parameters

POST JSON payload:

 
Example: 
      {"properties":[],"color":"#8ec8dc","name":"fs83","enabled":true}
HTTP Status Response
200 OK No content returned
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
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"properties":[],"color":"#8ec8dc","name":"fs83","enabled":true}' http://localhost:9090/api/1.0/dashboards/filterset

 

Update Filter Set

This endpoint is for updating/modifying the filter set on the chosen dashboard including filters in the filter set of a given filterset id

PUT /api/1.0/dashboards/<dashboardId>/filterset/<objectId>

Parameter Comments
dashboardId Dashboard id in which to update Filter Set
objectId Filter Set id to update

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: 
      {"properties":[{"visible":true,"enabled":true,"fieldName":"Bounced","fieldType":"java.lang.Integer","operator":"Not Equals","values":["1234567"],"dashboardDisplayValues":["1234"]}]}
HTTP Status Response
200 OK No content returned
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 dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"properties":[{"visible":true,"enabled":true,"fieldName":"Bounced","fieldType":"java.lang.Integer","operator":"Not Equals","values":["1234567"],"dashboardDisplayValues":["1234"]}]}' http://localhost:9090/api/1.0/dashboards/111064/filterset/102110

 

Make Filter Set Default

This endpoint is for making a filter set a default of a given filterset id

PUT /api/1.0/dashboards/<dashboardId>/filterset/<objectId>/default

Parameter Comments
dashboardId Dashboard id in which make Filter Set as default
objectId Filter Set id to make default
HTTP Status Response
200 OK No content returned
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 dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"properties":[{"fieldName":"Bounced","values":["1234567"],"operator":"Not Equals","type":"java.lang.Integer","enabled":true,"visible":true,"fieldType":"java.lang.Integer","fromFilterSet":true}]}' http://localhost:9090/api/1.0/dashboards/111064/filterset/102110/default

 

Reset Filter Set to Default

This endpoint is for resetting the filter set to default of a given filterset id

GET /api/1.0/dashboards/<dashboardId>/filterset/<objectId>/default

Parameter Comments
dashboardId Dashboard id in which reset Filter Set to default.
objectId Filter Set id to reset to default
HTTP Status Response
200 OK No content returned
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:
  • urrent user is not allowed to edit specified dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/dashboards/111064/filterset/102110/default

 

Share Filter set to Users/Groups

This endpoint is for sharing the filter set with the users/groups of a given filter id

PUT /api/1.0/dashboards/filterset/<objectId>/share

Parameter Comments
objectId Filter set id to share

POST 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
  • sso_user: Optional bool. Set to `true` if sharing to sso user
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "access_level" : 1, 
    "name" : "someUser1@host.com",
    "sso_user": true
  },
  { 
    "type" : "Groups", 
    "access_level" : 1, 
    "id" : 10001 
  } 
]
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> }
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. 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"access_level\" : 1, \"name\" : \"someUser@host.com\", \"sso_user\" : true } ] }"  http://localhost:9090/api/1.0/dashboards/filterset/102093/share

 

Delete Filter set

This endpoint is for deleting a filter set of a given filter id

DELETE /api/1.0/dashboards/filterset/<objectId>

Parameter Comments
objectId Filter set id to delete
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 filter sets
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/dashboards/filterset/102093

 

Add Widget to Dashboard

This endpoint is for adding a widget to the dashboard of a given widget id

PUT /api/1.0/dashboards/<objectId>/<widgetId>

Parameter Comments
objectId Dashboard Id where contained widget to add
widgetId Widget Id to add

PUT JSON payload:

Parameters Comments
row, col, size_x, size_y The location and size of the widget on dashboard. The dashboard's width is 24, and all widgets is within this bound.
Example: 
  { 
    "row" : 1, 
    "col" : 12, 
    "size_x" : 12,
    "size_y": 12
  }
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 col field
  • Missed row field
  • Missed size_x field
  • Missed size_y field
  • Unable to add widget to dashboard. Widget already exists on the dashboard
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 a dashboard
  • Current user is not allowed to edit specified dashboard
  • Current user is not allowed to access selected widget
  • Current user is not allowed to edit specified dashboard
  • Unable to add widget to dashboard because dashboard is locked
  • Adding widget to default dashboard is not allowed
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. 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"row\":1, \"col\":12, \"size_x\":12, \"size_y\":12}"  http://localhost:9090/api/1.0/dashboards/102093/26811

 

Remove Widget from Dashboard

This endpoint is for removing the Widget from the dashboard of a given widget id

DELETE /api/1.0/dashboards/<objectId>/<widgetId>

Parameter Comments
objectId Dashboard Id where contained widget is to be remove
widgetId Widget Id to remove
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:
  • Unable to remove chart from dashboard, because dashboard already haven't this widget
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 a dashboard
  • Current user is not allowed to edit specified dashboard
 
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/dashboards/102093/26811

GET Dashboard Share Properties

This endpoint returns and allows you to return/pull share properties associated with a dashboard (groups/users shared to).

GET /api/1.0/dashboards/<objectId>/share
Parameter Comments
objectId Dashboard id of Dashboard 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 dashboard
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 PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"access_level\" : 1, \"name\" : \"someUser@host.com\" } ] }" https://www.knowi.com/api/1.0/dashboards/110643/share

 

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

Related articles