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.

Management API (Beta)

Overview

Management API allows external services and apps to manage users and groups, datasources, queries, dashboards and widgets programmatically. The API is RESTful, and can be accessed via http://<service_host_and_port>/api/1.0/* url. Each request is stateless, with a response that includes an optional JSON object.

Enabling the Management API

To turn the API Management API, you must be an admin user and enable it. Navigate to the Settings (gear icon) -> User settings -> "Account settings" tab -> "Management API" row and click "Enable" to enable it. You will see your unique "client id" and "client secret", which you will need to access the system. Record and keep it securely.

Authentication

Overview

For authentication use OAuth 2.0 bearer access token in the HTTP headers of every request. Obtain a bearer token using your client id and client secret using the login end point. After the session, we also recommed using the logout end point to log out of the session. The default timeout for the bearer token is 1 hour, after which an UNAUTHORIZED (401) status code will be returned, at which point you will need again obtain new bearer access token using "login" command.

Typical workflow:

  • Obtain access token via login end point, keep the resulting bearer token in memory
  • Use the appropriate API end points as needed, passing in bearer token.
  • Call logout after use.

Login

To get bearer access token, turn on Management API in the User settings to obtan your "client id" and "client secret". Be sure to keep this in the safe place.

Query

POST /api/1.0/login

Parameter Comments
cliend_id client_id is a part of credentials obtained from User settings.
client_secret client_secret is a part of credentials obtained from User settings.
Response
HTTP Status Response
200 OK 
{
  "access_token": <Access Token used for API calls>,
  "token_type": <Type of Token> ("Bearer" always),
  "expires_in": <Number of seconds before the token expires> (by default - 3600 seconds)
}
400 BAD_REQUEST 
{ 
  "message": <Error details>, 
  "documentation_url": <Documentation link>
}

Error details:
  • Invalid parameters - missed client_id
  • Invalid parameters - missed client_secret
  • Management API disabled for this account
404 NOT_FOUND 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • Invalid credentials

Bearer access token

The returned by "login" bearer access token should be used in subsequent calls to the Management API in header named "Authorization":

Authorization: Bearer 69EuuRHieoidfbth48ygR9843wrgw94930g39845

Example
curl -i -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" http://localhost:9090/api/1.0/login

Logout

Call this end point to destroy the bearer token. You can re-issue a bearer token using the loginend point.

Query

DELETE /api/1.0/logout

No parameters
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
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/logout

Users

List Users

Query

GET /api/1.0/users

No parameters
Response
HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "id":10077,
         "username":"someEmail1@someHost.com",
         "name":"Test8",
         "customerId":1033,
         "autocycle":false,
         "tempUser":false,
         "ssoUser":false,
         "newUser":false,
         "timeZone":"America/Los_Angeles",
         "userGroups":[
            {
               "id":889,
               "groupName":"Default"
            },
            {
               "id":890,
               "groupName":"group1"
            },
            {
               "id":891,
               "groupName":"group2"
            }
         ],
         "roles":[
            "admin"
         ],
         "free":false,
         "twoFactorAuth":false
      },
      {
         "id":10081,
         "username":"someEmail2@someHost.com",
         "customerId":1033,
         "autocycle":false,
         "tempUser":false,
         "ssoUser":false,
         "newUser":false,
         "timeZone":"America/Los_Angeles",
         "userGroups":[
            {
               "id":890,
               "groupName":"group1"
            }
         ],
         "roles":[
            "admin"
         ],
         "free":false,
         "twoFactorAuth":false
      }
   ]
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

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

Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/users/

Get User

Query

GET /api/1.0/users/<user_id>

Parameter Comments
user_id User id to get info about specified User
Response
HTTP Status Response
200 OK Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

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

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

Error details:
  • Current user is not allowed to see specified user info
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/users/10001

Create User

Query

POST /api/1.0/users/

POST JSON payload:

Parameter Comments
username User name of new user, actually the existing email of new user
password Password for new user
phone Phone number for new user (required if using 2FA)
userInviteJson JSON of "invite" properties which include: user role (possible values: user, viewer, admin), user groups to which user will belong, which include group id, access level (possible values: 1, 2, where 1 - Edit rights, 2 - Read-only rights). Example: 
{
  "userGroups":
    [
      {
        "id":889,
        "access_level":1
      }
    ],
  "userRole":"viewer"
}
Response
HTTP Status Response
200 OK Return created user json info (same as "Get user" command). Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Invalid userInviteJson specified
  • Specified group is not exists
  • Invalid group specified
  • Invalid user role specified
  • Common error creating user via management api - details in the log at server
  • User limit reached
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
409 CONFLICT 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Error details:
  • User with such name already exists
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 "{\"username\":\"someEmail1@someHost.com\", \"password\":\"somePassword\", \"phone\":\"somePhone\", \"userInviteJson\": {\"userGroups\":[{\"id\":889,\"access_level\":1}],\"userRole\":\"viewer\"} }"  http://localhost:9090/api/1.0/users

Delete User

Query

DELETE /api/1.0/users/<user_id>

Parameter Comments
user_id User id of User 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:
  • Invalid json properties
  • Missed 'username' field in json
  • Missed 'password' field in json
  • Missed 'userInviteJson' field in json
  • Missed 'phone' field in json
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 user or user is not found
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/users/10084

Edit User

Query

PUT /api/1.0/users/<user_id>

Parameter Comments
user_id User id of the user to delete

PUT JSON payload. 
Any of fields are optional here (e.g. you can edit only required fields of user).

Parameter Comments
name Name of user (this is not username)
groups List of groups to which User is belongs, including access level (1 - Edit rights, 2 - read-only) Example of object: [{"name":"Default","id":889,"type":"Groups","access_level":1}]
roles Role of the account, could be: admin, user, viewer or custom role
contentFilters Optional (could be set to empty string), the content filters set to User. Example: [{"fieldName":"$c9_<field>$","type":"java.lang.String","values":["33"],"operator":"Equals"}]
timezone String timezone of the user location, e.g.: America/Los_Angeles
twoFactorAuth (BOOL value) Boolean value, if set to "true" then 2FA (two factor) authorisation is enabled for the account
phone Phone number of the account. Mostly useful together with "twoFactorAuth" variable
defaultDashboardId ID of dashboard to be shown whenever user login
autoShareTo Automatically share all assets created by user to the selected groups. This is useful within a team setting to collaborate on assets created by one user to be shared to others automatically, without sharing indivudal assets explicity. Shared assets includes any datasources, queries, widgets and dashboards. Value is array of json objects (groups) with "id" field in each of group to autoshare-to. Example, to auto-share to group with id 902: [{\"id\": 902 }]
Response
HTTP Status Response
200 OK Return created user json info (same as "Get user" command). Output example: 
{
   "id":10091,
   "username":"someEmail1@someHost.com",
   "customerId":1033,
   "autocycle":false,
   "tempUser":false,
   "ssoUser":false,
   "newUser":false,
   "timeZone":"America/Los_Angeles",
   "userGroups":[
      {
         "id":889,
         "groupName":"Default"
      }
   ],
   "roles":[
      "viewer"
   ],
   "free":false,
   "twoFactorAuth":false
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Common error saving user - details in the 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 edit specified user
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 "{\"name\":\"someName123\"}"  http://localhost:9090/api/1.0/users/10096

Groups

List Groups -- Current User

Query

GET /api/1.0/groups

No parameters
Response
HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "id":889,
         "groupName":"Default"
      },
      {
         "id":890,
         "groupName":"group1"
      },
      {
         "id":891,
         "groupName":"group2"
      }
   ]
}
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"  http://localhost:9090/api/1.0/groups/

List Groups - By User

Query

GET /api/1.0/users/<user_id>/groups

Parameter Comments
user_id User id of User to get Groups
Response
HTTP Status Response
200 OK Output example: 
{
   "list":[
      {
         "id":889,
         "groupName":"Default"
      },
      {
         "id":890,
         "groupName":"group1"
      },
      {
         "id":891,
         "groupName":"group2"
      }
   ]
}
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 user info
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/users/10001/groups/

Get Group Details (current user)

Query

GET /api/1.0/groups/<group_id>

Parameter Comments
group_id Group id of Group to get
Response
HTTP Status Response
200 OK Output example: 
{
  "id":890,
  "groupName":"group1"
}
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 group
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/groups/10001

Get Groups - By User

Query

GET /api/1.0/users/<user_id>/groups/<group_id>

Parameter Comments
userid User id of User to get specified Group in it
group_id Group id of Group to get info about inside specified User
Response
HTTP Status Response
200 OK Output example: 
{
  "id":890,
  "groupName":"group1"
}
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 group
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/users/10001/groups/90002

Create Group within current user

Query

POST /api/1.0/groups/

Parameter Comments
groupName Group name of new group
Response
HTTP Status Response
200 OK Return created group json info (same as "Get group" command). Output example: 
{
  "id":890,
  "groupName":"group1"
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Missed groupName field
  • Common error creating user group - 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
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -d "groupname=newGroupName1"  http://localhost:9090/api/1.0/groups

Create Group inside specified user

Query

POST /api/1.0/users/<user_id>/groups/

Parameter Comments
userid User id of User to create Group in it
groupName Group name of new group
Response
HTTP Status Response
200 OK Return created group json info (same as "Get group" command). Output example: 
{
  "id":890,
  "groupName":"group1"
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
Error details:
  • Missed groupName field
  • Common error creating user group - 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 edit specified user info
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -d "groupname=newGroupName1"  http://localhost:9090/api/1.0/users/10001/groups

Delete Group of current User

Query

DELETE /api/1.0/groups/<group_id>

Parameter Comments
group_id Group id of Group 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:
  • Failed to remove group - 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 group
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/groups/895

Delete Group of specified User

Query

DELETE /api/1.0/users/<user_id>/groups/<group_id>

Parameter Comments
userid User id of User to delete Group in it
group_id Group id of Group 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:
  • Failed to remove group - 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 group
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/users/10001/groups/895

Edit Group of current User

Query

PUT /api/1.0/groups/<group_id>

Parameter Comments
group_id Group id of Group to edit
groupName New group name of Group
Response
HTTP Status Response
200 OK Return updated group json info (same as "Get group" command). Output example: 
{
  "id":890,
  "groupName":"group1"
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

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

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

Error details:
  • Current user is not allowed to edit specified group
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X PUT -d "groupName=updatedGroupName1"  http://localhost:9090/api/1.0/groups/897

Edit Group of selected User

Query

PUT /api/1.0/users/<user_id>/groups/<group_id>

Parameter Comments
user_id User id where edit the Group
group_id Group id of Group to edit
groupName New group name of Group
Response
HTTP Status Response
200 OK Return updated group json info (same as "Get group" command). Output example: 
{
  "id":890,
  "groupName":"group1"
}
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

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

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

Error details:
  • Current user is not allowed to edit specified group
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X PUT -d "groupName=updatedGroupName1"  http://localhost:9090/api/1.0/users/10001/groups/897

Dashboards

List Dashboards

Query

GET /api/1.0/dashboards

No parameters
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"  http://localhost:9090/api/1.0/dashboards/

Get Dashboard

Query

GET /api/1.0/dashboards/<objectId>

Parameter Comments
objectId Dashboard id to view Dashboard
Response
HTTP Status Response
200 OK 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
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
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/dashboards/10001

Share Dashboard via Url

Query

GET /api/1.0/dashboards/<objectId>?shareViaUrl=true

Parameter Comments
objectId Id of Dashboard to share
object_id "shareViaUrl" is query param, only possible value is "true", meaning this will be sharing Dashboard via Url
Response
HTTP Status Response
200 OK Output example: 
{
 "dashShareUrlKey": "x5UJADiifFZoYS6iix2ADwEJsii30Qljj7eUcNKfcSMduMie"
}

Use the dashShareUrlKey to construct the full url by adding /d/ and the "dashShareUrlKey" to the host name and port. If service host and port is "localhost:9090" then the constructed url from above example is: http://localhost:9090/d/x5UJADiifFZoYS6iix2ADwEJsii30Qljj7eUcNKfcSMduMie
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:
  • Some error occurred during sharing 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 access specified dashboard
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/dashboards/10001?shareViaUrl=true

Share Dashboard to Users/Groups

Query

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

Parameter Comments
objectId Dashboard id of Dashboard 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 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\" } ] }"  http://localhost:9090/api/1.0/dashboards/110643/share

Create Dashboard

Query

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}"  http://localhost:9090/api/1.0/dashboards

Delete Dashboard

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 http://localhost:9090/api/1.0/dashboards/10084

Edit Dashboard

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 List of 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
  • Missed categories 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\" : [ \"category1\"]}"  http://localhost:9090/api/1.0/dashboards/10001

Clone 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
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}" http://localhost:9090/api/1.0/dashboards/110643

List Widgets in Dashboard

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"  http://localhost:9090/api/1.0/dashboards/10001/widgets

Export dashboard to PDF

Query

GET /api/1.0/dashboards/<objectId>/export/pdf

Parameter Comments
objectId Dashboard id to export to PDF
Response
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
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/dashboards/10001/export/pdf > file1.pdf

Widgets

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"  http://localhost:9090/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"  http://localhost:9090/api/1.0/widgets/10001

Share Widget via Url

Query

GET /api/1.0/widgets/<objectId>?shareViaUrl=true

Parameter Comments
objectId Id of Widget to share
object_id "shareViaUrl" is query param, only possible value is "true", meaning this will be sharing Widget via Url
Response
HTTP Status Response
200 OK Output example: 
{
 "widgetShareUrlKey": "x5UJADiifFZoYS6iix2ADwEJsii30Qljj7eUcNKfcSMduMie"
}

Use the widgetShareUrlKey to construct the full url by adding /w/ and the "widgetShareUrlKey" to the host name and port. If service host and port is "localhost:9090" then the constructed url from above example is: http://localhost:9090/w/x5UJADiifFZoYS6iix2ADwEJsii30Qljj7eUcNKfcSMduMie
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:
  • Some error occurred during sharing widget - 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 access specified widget
Example
curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/widgets/5002?shareViaUrl=true

Share Widget to Users/Groups

Query

PUT /api/1.0/widgets/<objectId>/share

Parameter Comments
objectId Widget id of Widget 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.
 
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\" } ] }"  http://localhost:9090/api/1.0/widgets/110643/share
Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles