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/

 

Get Widget

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

 

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 Widget name
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:
  • 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 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

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

 

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
cloneWithData boolean variable, meaning if need to clone with data
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\",\"cloneWithData\":true}" 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

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