Login
Start Trial
Request Demo

Management API

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 https:///api/1.0/ url. Each request is stateless, with a response that includes an optional JSON object.

The default Knowi Management API host is https://knowi.com/api/1.0/

Enabling the Management API

To turn the API Management API, you must be an admin user and enable it from the User Settings.

To enable, navigate to the Settings -> User settings -> "Account settings" tab -> "Management API" row and click "Enable".

At any time you can generate new credentials by disabling your existing credentials and re-enabling.

API 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 recommendd 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:

Login

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

Query

POST /api/1.0/login

Parameter Comments
client_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 login end 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

    User Management

    List Users

    This endpoint returns a listing the information of all the users in the workspace

    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

    This endpoint returns all the information about a specific user of a given user Id

    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

    Search User by Username

    This endpoint returns a user detail of a given username

    Query

    GET /api/1.0/users/search

    Parameter Comments
    userType the type of user to filter results (regular|sso|external)
    username the username to search
    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 HEREISYOUR_BEARER" https://www.knowi.com/api/1.0/users/search?username=email@acme.com&userType=sso

    Create User

    This endpoint is for creating a new user with specified information

    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 It is used to make and receive calls, send and receive text messages (SMS) linked to your account, and is also required in Two Factor Authentication (2FA) to log into Knowi.
    userGroups userGroups is a nested object that contains object here for backward compatibility the following properties are:

    id: This is an id of the group
    accessLevel: This is a level of the access
    userRole This is the role of a user.
    autoShareTo Automatically share all assets created and linked to a user with the selected groups. This is useful within a team setting to collaborate on assets created by one user to be transferred to others automatically, without sharing individual assets explicitly. Shared assets include any datasources, queries, widgets, and dashboards. Value is an array of JSON objects (groups) with an "id" field in each of groups to autoShareTo. For example, to auto-share to group with id 902: [{\"id\": 902 }]
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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.
    twoFactorAuth User enters their username and password to log in, Once the credentials are verified, the system prompts the user for a second factor of authentication and gets verified Via SMS or Via Email. Boolean value, if set to "true" then two-factor authorization (2FA) is enabled for the account
    limitListingUsersToGroups Limit sharing to groups. When set, this user will only see other users within the same groups to be able to share assets to.
    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 does 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
  • Username parameter can't be empty
    • 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": "somePas1234Gfgsword", "phone": "somePhone", "userGroups": [{"id": 889, "accessLevel": 1}], "userRole": "viewer", "autoShareTo": [{"id": 889, "accessLevel": 1}], "contentFilters": [{"fieldName": "Customer", "values": ["Facebook"], "operator": "="}], "twoFactorAuth": "false", "limitListingUsersToGroups": false}' "http://localhost:9090/api/1.0/users"

    Delete User

    This endpoint is for deleting a specific user of a given user id

    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?move_to=10085

    Transfer User Assets to Another User

    This endpoint is for moving the user assets to another user of a given user id

    Query

    PUT /api/1.0/users/<userId>/moveAssets?toUserId=123456

    Parameter Comments
    userId User id of source user to transfer assets from
    toUserId User id of destination user to transfer assets to
    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 PUT http://localhost:9090/api/1.0/users/10084/moveAssets?toUserId=10085

    Edit User

    This endpoint is for updating/modifying the user details of a given user id

    Query

    PUT /api/1.0/users/<user_id>

    Parameter Comments
    user_id User id of the user to edit

    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","accessLevel":1}]
    roles Role of the account, could be: admin, user, viewer or custom role
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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.
    timezone String timezone of the user location, e.g.: America/Los_Angeles
    twoFactorAuth (BOOL value) User enters their username and password to log in, Once the credentials are verified, the system prompts the user for a second factor of authentication and gets verified Via SMS or Via Email. Boolean value, if set to "true" then two-factor authorization (2FA) is enabled for the account
    phone It is used to make and receive calls, send and receive text messages (SMS) linked to your account, and is also required in Two Factor Authentication (2FA) to log into Knowi.
    defaultDashboardId ID of dashboard to be shown whenever user login
    autoShareTo Automatically share all assets created and linked to a user with the selected groups. This is useful within a team setting to collaborate on assets created by one user to be transferred to others automatically, without sharing individual assets explicitly. Shared assets include any datasources, queries, widgets, and dashboards. Value is an array of JSON objects (groups) with an "id" field in each of groups to autoShareTo. For example, to auto-share to group with id 902: [{\"id\": 902 }]
    limitListingUsersToGroups Limit sharing to groups. When set, this user will only see other users within the same groups to be able to share assets to.
    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

    This endpoint returns a listing of all the groups

    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/

    User Groups

    This endpoint returns a listing the groups of a specific user of a given user id

    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/

    Group Details

    This endpoint returns all the groups of a given group id

    Query

    GET /api/1.0/groups/<group_id>

    Parameter Comments
    group_id Group id of Group to get
    withSharing Optional query parameter, value (boolean) true/false. Default value is false. If true, then output will contain list of assets shared into group, and also autoShareUsers field with list of Users which autoShared into this group (only available if user have permissions to list Users of Customer).
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "id":890,
  "groupName":"group1",
  "dashboards":[],
  "charts":[{"accessLevel":1,"name":"An Chart","objectId":26563}],
  "queries":[],
  "datasources":[],
  "autoShareUsers":[{"ssoUser":false,"name":"an user name","externalAuthId":0,"id":10093,"userName":"someEmail1@someHost.com"}]
}
    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?withSharing=true

    User Groups

    This endpoint returns listing of all the groups which are assigned to a specific 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
    withSharing Optional query parameter, value (boolean) true/false. Default value is false. If true, then output will contain list of assets shared into group, and also autoShareUsers field with list of Users which autoShared into this group (only available if user have permissions to list Users of Customer).
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "id":890,
  "groupName":"group1",
  "dashboards":[],
  "charts":[{"accessLevel":1,"name":"An Chart","objectId":26563}],
  "queries":[],
  "datasources":[],
  "autoShareUsers":[{"ssoUser":false,"name":"an user name","externalAuthId":0,"id":10093,"userName":"someEmail1@someHost.com"}]
}
    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?withSharing=true

    Creating Group

    This endpoint is for creating a new group

    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 a Group with User

    This endpoint is for creating a group with a user of a given user id

    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

    Deleting Group

    This endpoint is for deleting a specific group of a given group id

    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

    This endpoint is for deleting a group that is assigned to a 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

    This endpoint is for deleting a group of a given group id

    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

    This endpoint is for updating/modifying a group of the selected user of a given group id

    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

    This endpoint returns a listing of all the dashboards

    Query

    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
    Error details:
  • Invalid category filter parameters
    • 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?byCategory=123,642

    Get Dashboard Details

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

    Query

    GET /api/1.0/dashboards/<objectId>

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

    Generate Dashboard Share Url

    This endpoint is for generating a dashboard share URL

    Query

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

    Parameter Comments
    objectId Dashboard id to update share url with new share hash and generate and return the newly generated hash together with content filters
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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 set to false and the dashboard does NOT have share or secure share (respectively) enabled, the endpoint will try to enable it
    Response
    HTTP Status Response
    200 OK Output example: 
    {
 "shareUrl": "4PdpqevhrfPYxmof6t2mbRkzuzXcAbmxWJhtip38VmrQie?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/4PdpqevhrfPYxmof6t2mbRkzuzXcAbmxWJhtip38VmrQie?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
    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
    • Example
    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

    Query

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

    Parameter Comments
    objectId Dashboard id to update secure share url with new share hash and generate and return the newly generated hash together with content filters
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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 set to false and the dashboard does NOT have share or secure share (respectively) enabled, the endpoint will try to enable it
    Response
    HTTP Status Response
    200 OK Output example: 
    {
 "secureShareUrl": "kN3Gj9jipB458gipMJ8EoaeC8rWfny3kp2XIPamz8V9PQie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___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/kN3Gj9jipB458gipMJ8EoaeC8rWfny3kp2XIPamz8V9PQie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww==
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Customer token is missing, can't encrypt content filters
    • Error details:
  • Current user is not allowed to generate dashboard secure share url
    • 401 UNAUTHORIZED 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

    Error details:
  • Current user is not allowed to generate dashboard secure share url
    • Example
    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.

    Query

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

    Parameter Comments
    objectId Dashboard id to generate secure share url
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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.
    Response
    HTTP Status Response
    200 OK Output example: 
    {
 "secureHash": "kN3Gj9jipB458gipMJ8EoaeC8rWfny3kp2XIPamz8V9PQie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___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/kN3Gj9jipB458gipMJ8EoaeC8rWfny3kp2XIPamz8V9PQie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww==
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Customer token is missing, can't encrypt content filters
    • Error details:
  • Current user is not allowed to generate dashboard secure share url
    • 401 UNAUTHORIZED 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

    Error details:
  • Current user is not allowed to generate dashboard secure share url
    • Example
    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":"="}]'

    Get Dashboard Share Info

    This endpoint retrieves a list of users and groups with whom the dashboard has been shared.

    Query

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

    Parameter Comments
    objectId Dashboard id of Dashboard to share
    Response
    HTTP Status Response
    200 OK JSON object with list of users and groups with whom the dashboard has been shared. Output example: 
     {
  "list": [
    {
      "id": 10222,
      "type": "Users",
      "name": "euler (Leonhard Euler)",
      "accessLevel": 1
    },
    {
      "id": 890,
      "type": "Groups",
      "name": "group1",
      "accessLevel": 1
    }
  ]
}
    Note: If a dashboard hasn't been shared to any user or group, endpoint will return an empty list.
    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 view specified dashboard
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/dashboards/110643/share

    Share Dashboard to Users/Groups

    This endpoint is for sharing the dashboard with users or groups of a given dashboard id

    Query

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

    Parameter Comments
    objectId Dashboard id of Dashboard to share
    ssoUser 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.
  • accessLevel: 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", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com" 
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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\", \"accessLevel\" : 1, \"name\" : \"someUser@host.com\" } ] }"  http://localhost:9090/api/1.0/dashboards/110643/share

    Create Dashboard

    This endpoint is for creating a new 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

    This endpoint is for deleting a dashboard of given dashboard 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 http://localhost:9090/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 Array list of categories IDs to assign
    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
  • Current user is not allowed to add into category with id {id}
    • 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\" : [ 123, 456 ]}"  http://localhost:9090/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
    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

    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 Optional parameter. Category id to filter by.
    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,
         "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:
  • Invalid category filter parameters
    • 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?byCategory=123,923

    Export dashboard to PDF

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

    Query

    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. It is optional (can be skipped or set to empty string) 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.
    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?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

    Query

    GET /api/1.0/dashboards/filterset

    Response
    HTTP Status Response
    200 OK Output example: 
    [
    {
        "createdDate": null,
        "lastModDate": 1565638416000,
        "id": 102092,
        "userId": 1214,
        "name": "filterset",
        "accessLevel": 1,
        "filters": [
            {
                "fieldName": "Customer",
                "values": [
                    "Costco",
                    "Facebook",
                    "Macy's"
                ],
                "operator": "Equals",
                "type": "java.lang.String",
                "enabled": true,
                "visible": true,
                "transientFilter": false,
                "fieldType": "java.lang.String"
            }
        ]
    }
]
    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
    • Example
    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 id

    Query

    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
    }
  ],
  "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
    }
  ]
}
    Response
    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
    • Example
    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.

    Query

    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
    }
  ]
}
    Response
    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"
    • Example
    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

    Query

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

    Parameter Comments
    objectId Dashboard id in which reset user filters to default filters
    Response
    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
    • Example
    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

    Query

    POST /api/1.0/dashboards/filterset

    No parameters

    POST JSON payload:
    Example: 
          {"properties":[],"color":"#8ec8dc","name":"fs83","enabled":true}
    Response
    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
    • Example
    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

    Query

    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 variety 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"]}]}
    Response
    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
    • Example
    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 default of a given filterset id

    Query

    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
    Response
    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
    • Example
    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

    Query

    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
    Response
    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
    • Example
    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

    Query

    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.
  • accessLevel: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • ssoUser: Optional bool. Set to `true` if sharing to sso user
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com",
    "ssoUser": true
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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.
    Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"accessLevel\" : 1, \"name\" : \"someUser@host.com\", \"ssoUser\" : 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

    Query

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

    Parameter Comments
    objectId Filter set 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 filter sets
    • Example
    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

    Query

    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
  }
    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 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.
    Example
    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

    Query

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

    Parameter Comments
    objectId Dashboard Id where contained widget is to be remove
    widgetId Widget Id to remove
    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:
  • 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
    • Example
    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).

    Query

    GET /api/1.0/dashboards//share

    Parameter Comments
    objectId Filter set id to share

    POST JSON payload:

    Parameter Comments
    shareProperties Share properties json array. Available fields:
  • Type: Users, Groups.
  • accessLevel: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • ssoUser: Optional bool. Set to `true` if sharing to sso user
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com",
    "ssoUser": true
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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.
    Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"accessLevel\" : 1, \"name\" : \"someUser@host.com\", \"ssoUser\" : true } ] }"  http://localhost:9090/api/1.0/dashboards/filterset/102093/share

    Widgets

    List Widgets

    This endpoint returns a listing of widgets of a given category

    Query

    GET /api/1.0/widgets?byCategory=<byCategory>

    Parameter Comments
    byCategory Optional parameter. Comma separated list of categories IDs to filter by. Multiple categories applied as OR operator.
    pagination Set to true to enable pagination. This is required for paginated requests.
    limit Optional parameter. Maximum number of widgets to return per page. Works only if pagination set to true. Default is 100.
    paginationBookmark The bookmark from the previous request to fetch the next page of widgets. Use the nextBookmark field from the previous response.
    Response
    HTTP Status Response
    200 OK Output example: 
    {
   "nextBookmark": "123",
   "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,
         "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:
  • Invalid category filter parameters
    • 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?byCategory=123,642

    List Widget Alerts

    This endpoint returns a listing of widget alerts of a given widget id

    Query

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

    Parameter Comments
    objectId Widget id to list alerts in it
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "list": [
    {
      "createdDate": 1648134840000,
      "lastModDate": 1648134840000,
      "id": 242,
      "datasetId": 16170,
      "lastAlert": null,
      "sendToOld": null,
      "userId": 10077,
      "alertCondition": "select * where Sent > 100",
      "dataset": null,
      "alertName": "alert12",
      "alertType": 4,
      "lastDataMeta": null,
      "accessLevel": 1,
      "scheduleId": 105,
      "schedule": {
        "frequencyType": "minute",
        "frequency": 15,
        "startTime": null,
        "cronConfig": "*/15 * * * *",
        "id": 105,
        "type": 0,
        "host": null,
        "createdDate": 1648134840000,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 1648124040,
        "nextExecutionTime": 1648124040000
      },
      "realtime": true,
      "executionReport": null,
      "firedCount": 0,
      "createdBy": null,
      "deletable": false,
      "chartId": 26908,
      "lastDataMetaObj": null,
      "properties": {
        "classVersion": 2,
        "emailOutput": {
          "classVersion": 1,
          "from": "support@knowi.com",
          "sendTo": "Some@some.com",
          "cc": "",
          "bcc": "",
          "emailSubject": "alert10",
          "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
          "attachDataset": false,
          "attachResultsAfterCloud9ql": false
        },
        "webhookOutput": {
          "classVersion": 1,
          "selectedWebhooks": [
            200
          ]
        },
        "configAttachment": false,
        "attachmentConfig": {
          "datasetId": null,
          "query": ""
        },
        "alertIfNoData": false,
        "skipSameAlert": true,
        "attachAlertData": true,
        "frequencyMarker": "custom",
        "operator": ">",
        "metric": "Sent",
        "threshold": "100"
      }
    },
    {
      "createdDate": 1648121285000,
      "lastModDate": 1648121285000,
      "id": 240,
      "datasetId": 16170,
      "lastAlert": null,
      "sendToOld": null,
      "userId": 10077,
      "alertCondition": "select * where Sent > 100",
      "dataset": null,
      "alertName": "alert12",
      "alertType": 4,
      "lastDataMeta": null,
      "accessLevel": 1,
      "scheduleId": 103,
      "schedule": {
        "frequencyType": "minute",
        "frequency": 15,
        "startTime": null,
        "cronConfig": "*/15 * * * *",
        "id": 103,
        "type": 0,
        "host": null,
        "createdDate": 1648121285000,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 1648110485,
        "nextExecutionTime": 1648110485000
      },
      "realtime": true,
      "executionReport": null,
      "firedCount": 0,
      "createdBy": null,
      "deletable": false,
      "chartId": 26908,
      "lastDataMetaObj": null,
      "properties": {
        "classVersion": 2,
        "emailOutput": {
          "classVersion": 1,
          "from": "support@knowi.com",
          "sendTo": "Some@some.com",
          "cc": "",
          "bcc": "",
          "emailSubject": "alert10",
          "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
          "attachDataset": false,
          "attachResultsAfterCloud9ql": false
        },
        "webhookOutput": {
          "classVersion": 1,
          "selectedWebhooks": [
            200
          ]
        },
        "configAttachment": false,
        "attachmentConfig": {
          "datasetId": null,
          "query": ""
        },
        "alertIfNoData": false,
        "skipSameAlert": true,
        "attachAlertData": true,
        "frequencyMarker": "custom",
        "operator": ">",
        "metric": "Sent",
        "threshold": "100"
      }
    }
  ]
}
    400 BAD REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to see the alerts
  • Current user is not allowed to access specified widget
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26908/alerts

    Get Widget Details by Id

    This endpoint is to return the details of the widget, and also includes the ?filters" and ?defaultFilters" fields inside "widgetConfig" in by widget id

    Query

    GET /api/1.0/widgets/<objectId>

    URL Parameters
    Parameter Comments Type
    widgetId Widget ID to retrieve Number
    Query Parameters
    Parameter Comments Type Default
    loadData Whether or not to load widget data Boolean True
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "createdDate": 1560856775000,
  "lastModDate": null,
  "id": 26559,
  "name": "sendingActivity",
  "userId": 10077,
  "customerId": 1033,
  "datasetId": 15848,
  "type": 1,
  "description": "descr2",
  "urlString": "4Mbaii",
  "access": 0,
  "refreshChartMillis": -1,
  "jsonConfig": "{\"filters\":[{\"fieldName\":\"clicks\",\"visible\":true,\"transientFilter\":false,\"values\":[\"1005\"],\"type\":\"java.lang.Integer\",\"fieldType\":\"java.lang.Integer\",\"operator\":\"Greater than\",\"enabled\":true}]}",
  "shareUrl": null,
  "accessLevel": -1,
  "dashboardAccessLevel": -1,
  "categoryAccessLevel": -1,
  "autoShared": false,
  "urlShareWhitelistDomain": null,
  "filterSettings": null,
  "chartType": "band",
  "alertCount": 0,
  "queryId": -1,
  "queryStr": null,
  "adhocQuery": "select message_type, customer, date, week,\n  clicks, spam, campaign_name,\n  message_type as message_type2",
  "categories": [],
  "userExternalAuthId": 0,
  "userSso": false,
  "drilldown": false,
  "dataset": {
    "createdDate": 1560856775000,
    "lastModDate": null,
    "id": 15848,
    "metadataConfig": "{\"fields\":[{\"fieldName\":\"bounced\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"campaign_name\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"clicks\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"conversions\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"customer\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"date\",\"fieldType\":\"java.util.Date\"},{\"fieldName\":\"delivered\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"id\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"message_type\",\"fieldType\":\"java.lang.String\"},{\"fieldName\":\"opened\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"sent\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"spam\",\"fieldType\":\"java.lang.Integer\"},{\"fieldName\":\"week\",\"fieldType\":\"java.util.Date\"}]}",
    "lastUpdateDate": 1560856775000,
    "mongoId": null,
    "mongoConnectUri": "localhost:27017/Some_a3PNFK",
    "customerId": 1033,
    "datasetName": "sendingActivity2019-06-18-11-19",
    "identifier": "4Mbaii",
    "userId": 0,
    "refreshMeta": false,
    "injectStreamTime": true,
    "nlpEnabled": true,
    "nlpBotEnabled": true,
    "nlpConfig": null,
    "customer": null,
    "metaData": {
      "fields": [
        {
          "fieldName": "bounced",
          "fieldType": "java.lang.Integer"
        },
        {
          "fieldName": "campaign_name",
          "fieldType": "java.lang.String"
        },
        ...,
        {
          "fieldName": "week",
          "fieldType": "java.util.Date"
        }
      ],
      "dataTypes": {
        "bounced": "java.lang.Integer",
        "campaign_name": "java.lang.String",
        ...,
        "week": "java.util.Date"
      },
      "fieldNames": [
        "bounced",
        "campaign_name",
        ...,
        "week"
      ]
    },
    "direct": false
  },
  "position": {
    "chartId": 0,
    "width": 500,
    "height": 400,
    "originalScreenWidth": 0,
    "originalScreenHeight": 0,
    "col": 0,
    "row": 0,
    "ypos": 0,
    "xpos": 0,
    "id": 0,
    "size_x": 0,
    "size_y": 0
  },
  "associations": null,
  "queryModified": false,
  "updateFilters": false,
  "dataFields": [
    "message_type",
    "customer",
    "date",
    "week",
    "clicks",
    "spam",
    "campaign_name",
    "message_type2"
  ],
  "dataFieldsTypes": {
    "message_type": "java.lang.String",
    "customer": "java.lang.String",
    "date": "java.util.Date",
    "week": "java.util.Date",
    "clicks": "java.lang.Integer",
    "spam": "java.lang.Integer",
    "campaign_name": "java.lang.String",
    "message_type2": "java.lang.String"
  },
  "transientChartFilters": null,
  "typeModified": false,
  "lastSyncDate": 1560856775000,
  "viewOnly": false,
  "truncated": null,
  "processedName": "sendingActivity2019-06-18-11-19 2019-06-18T04:19:35",
  "processedDescription": "descr2 2019-06-18T04:19:35",
  "processedFootNote": "foot2 2019-06-18T04:19:35",
  "error": null,
  "widgetConfig": {
    "filters": [
      {
        "fieldName": "clicks",
        "values": [
          "1005"
        ],
        "operator": "Greater than",
        "type": "java.lang.Integer",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "fieldType": "java.lang.Integer"
      }
    ],
    "defaultFilters": [
      {
        "fieldName": "clicks",
        "values": [
          "1005"
        ],
        "operator": "Greater than",
        "type": "java.lang.Integer",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "fieldType": "java.lang.Integer"
      }
    ]
  },
  "notDefaultFilter": false,
  "chartProperties": {
    "chart.historical_y_axis": "clicks",
    "chart.band_x_axis": "date",
    "widget.footnote": "foot2 $c9_DataLastUpdate_${date|yyyy-MM-ddTHH:mm:ss}$",
    "chart.type": "band",
    "pivot.columnWidths": "{\"name\":296.75}",
    "pivot.sort": "{\"id\":\"name\",\"dir\":\"asc\"}",
    "chart.series.type": "time",
    "chartColor": "#89D4F5:clicks,#BCD759:spam,#FFBF00,#9961A7,#4891EA,#EE965B,#F284D1,#6FDBCB,#2D71C4,#EF5A5A,#609C29,#C69B06,#8A2299,#996D6C,#2F2F6C,#1C6C61",
    "chart.quickpickers": "0",
    "pivot.structure": "..."
  },
  "xAxis": null,
  "yAxis": null,
  "dataJSONArr": [
    {
      "name": "clicks",
      "id": "sendingActivity",
      "data": [
        {
          "name": 1419926400000,
          "x": 1419926400000,
          "y": 3311
        },
        {
          "name": 1419926400000,
          "x": 1419926400000,
          "y": 7274
        },
        {
          "name": 1419926400000,
          "x": 1419926400000,
          "y": 28278
        }
      ],
      "type": "line",
      "zIndex": "0",
      "zoneAxis": "x",
      "color": "#E61BCB",
      "legend_title": "Actual value"
    }
  ],
  "chartMarkers": null,
  "dataGroup": null,
  "gridBean": null,
  "xaxisJSONArr": null,
  "yaxisJSONArr": null,
  "filters": [
    {
      "fieldName": "clicks",
      "values": [
        "1005"
      ],
      "operator": "Greater than",
      "type": "java.lang.Integer",
      "enabled": true,
      "visible": true,
      "transientFilter": false,
      "fieldType": "java.lang.Integer"
    }
  ],
  "widgetAccessLevel": -1,
  "chartPropertiesNullOrEmpty": false,
  "filterFieldDataTypes": {
    "bounced": "java.lang.Integer",
    "campaign_name": "java.lang.String",
    "clicks": "java.lang.Integer",
    "conversions": "java.lang.Integer",
    "customer": "java.lang.String",
    "date": "java.util.Date",
    "delivered": "java.lang.Integer",
    "id": "java.lang.String",
    "message_type": "java.lang.String",
    "opened": "java.lang.Integer",
    "sent": "java.lang.Integer",
    "spam": "java.lang.Integer",
    "week": "java.util.Date"
  },
  "processedFilters": [
    {
      "fieldName": "clicks",
      "values": [
        "1005"
      ],
      "operator": "Greater than",
      "type": "java.lang.Integer",
      "enabled": true,
      "visible": true,
      "transientFilter": false,
      "fieldType": "java.lang.Integer"
    }
  ],
  "live": true,
  "dataDisplayTypes": {},
  "dbFields": [
    "bounced",
    "campaign_name",
    ...,
    "week"
  ],
  "ignoreVals": [
    "date",
    "conversions",
    ...,
    "customer"
  ],
  "widgetTypeStr": "chart",
  "filterFieldDataTypesIncludingNested": {
    "bounced": "java.lang.Integer",
    "campaign_name": "java.lang.String",
    ...,
    "week": "java.util.Date"
  }
}
    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

    Generate and replace Widget Share Url

    This endpoint is for generating and replace the existing widget share URL of a given widget id

    Query

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

    Parameter Comments
    objectId Widget id to generate share url
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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.
    Response
    HTTP Status Response
    200 OK Output example: 
    {
 "shareUrl": "Zar1OtKVb7iiiiV6Ufa8VJ25Wo3jvrPI1aySdisvceplMEie?contentFilters=%5B%7B%22fieldName%22%3A%22Customer%22%2C%22values%22%3A%5B%22Facebook%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D"
}

    Note: To construct the full url, prepend /w/ and the ?shareUrl" to the host name and port. For example: http://localhost:9090/w/Zar1OtKVb7iiiiV6Ufa8VJ25Wo3jvrPI1aySdisvceplMEie?contentFilters=%5B%7B%22fieldName%22%3A%22Customer%22%2C%22values%22%3A%5B%22Facebook%22%5D%2C%22operator%22%3A%22%3D%22%7D%5D
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
    • Error details:
  • Current user is not allowed to generate widget share url
    • 401 UNAUTHORIZED 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

    Error details:
  • Current user is not allowed to generate widget share url
    • Example
    curl -X POST -i http://localhost:9090/api/1.0/widgets/3528/share/url -H 'Authorization: Bearer HERE_IS_YOUR_BEARER' -H 'Content-Type: application/x-www-form-urlencoded' -d 'contentFilters=[{"fieldName":"Customer","values":["Facebook"],"operator":"="}]'

    Share Widget Secure Url

    This endpoint is for sharing the widget secure URL of a given widget id

    Query

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

    Parameter Comments
    objectId Widget id to generate secure share url
    contentFilters It is an array of filters, used to filter content for users on dashboards and widgets that defines the field name, Type of field, value of that field, and Operator. It is optional (can be skipped or set to empty string). Example: 
    [{"fieldName":"$c9_$", "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.
    Response
    HTTP Status Response
    200 OK Output example: 
    {
 "secureShareUrl": "S0jBEWZ2WLNCCe8pXQYtTbip3zrq3oaM8iplCQDzEhpEkie/dnqPwU7UF61jmT+rgIft4aEY1kWQ1B1V4FWGoIGITmZGl___n3P859PnDoJlcSiov6CIWd___8Dpvl5JH74SIhJxww=="
}

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

    Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Customer token is missing, can't encrypt content filters
    • Error details:
  • Current user is not allowed to generate widget secure share url
    • 401 UNAUTHORIZED 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

    Error details:
  • Current user is not allowed to generate widget secure share url
    • Example
    curl -X POST -i http://localhost:9090/api/1.0/widgets/3528/share/url/secure -H 'Authorization: Bearer HERE_IS_YOUR_BEARER' -H 'Content-Type: application/x-www-form-urlencoded' -d 'contentFilters=[{"fieldName":"Customer","values":["Facebook"],"operator":"="}]'

    Get widget dataset query mapper

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

    Query

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

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

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

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

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

    Share Widget to Users/Groups

    This endpoint is for sharing the widget to users and groups of a given widget id

    Query

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

    Parameter Comments
    objectId Widget id of Widget to share
    ssoUser 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.
  • accessLevel: 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", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com" 
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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\", \"accessLevel\" : 1, \"name\" : \"someUser@host.com\" } ] }"  http://localhost:9090/api/1.0/widgets/110643/share

    Create Widget

    This endpoint is for creating a new widget

    Query

    POST /api/1.0/widgets/

    POST JSON payload:

    Parameter Comments
    datasetId Id of Dataset to use to create Widget
    widgetName (String) Widget name
    widgetType Optional integer. Widget type. It is works togeter with "chart.type" parameter inside chartProperties to set actual chart kind.
    chartProperties Optional string. JSON with all chart properties. To get an example of this JSON you can get example of your chart properties from your existing widget (using Get Widget Details command), which contains chartProperties field.
    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,
 "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
  • Wrong chartProperties format
    • 401 UNAUTHORIZED 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

    Error details:
  • Current user is not allowed to add widget using specified dataset
  • Have no permissions to add new widget
  • Widget limit reached
    • 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\"}" http://localhost:9090/api/1.0/widgets

    Delete Widget

    This endpoint is for deleting a widget of a given widget id

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

    Edit Widget

    This endpoint is for updating/modifying a widget of a given widget id

    Query

    PUT /api/1.0/widgets/<objectId>

    Parameter Comments
    objectId Widget id of Widget to edit

    PUT JSON payload:

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

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

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

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

 ],
 "processedFilters":[

 ]
}
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

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

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

    Reset user filters to Default for Widget

    This endpoint is for removing the user filters and set default filters of a given widget id

    Query

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

    Parameter Comments
    objectId Widget id in which to reset user filters to defaault filters
    Response
    HTTP Status Response
    200 OK Output example: Output Widget entity with updated filters
    400 BAD REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to edit specified widget
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/widgets/26559/filter/reset

    Update Default Filters for Widget

    This endpoint is for updating/modifying the default filters for a widget of a given widget id

    Query

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

    Parameter Comments
    objectId Widget id in which to update default filters

    PUT JSON payload:
    To get all varity of input parameters, please create filter in UI first, and then get/list it with another endpoint to investigate possible inputs. It may be changed in future versions.
    Example: 
          {"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}
    Response
    HTTP Status Response
    200 OK Output the widget with updated default filters>
    400 BAD REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to edit specified widget
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"filters":[{"fieldName":"clicks","visible":true,"transientFilter":false,"values":["1005"],"type":"java.lang.Integer","fieldType":"java.lang.Integer","operator":"Greater than","enabled":true}]}'  http://localhost:9090/api/1.0/widgets/26559/filter/default

    Clone Widget

    This Endpoint is for cloning/copying a widget of a given widget id

    Query

    POST /api/1.0/widgets/<objectIdToClone>

    Parameter Comments
    objectIdToClone Widget id of Widget to clone

    POST JSON payload:

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

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

 ],
 "gridBean":null,
 "dataRow":null,
 "text":"",
 "colNames":null,
 "dataRows":null,
 "live":false,
 "filters":null,
 "widgetType":"DATA_GRID",
 "macros":null,
 "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\"}"  http://localhost:9090/api/1.0/widgets/12345

    Export widget to PDF

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

    Query

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

    Parameter Comments
    objectId Widget 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 widget, which allows using of the same widget 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": "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.
    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/widgets/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

    Reports

    List Reports

    This endpoint returns a listing of all reports

    Query

    GET /api/1.0/reports

    No parameters
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "list": [
    {
      "createdDate": 1648071581000,
      "lastModDate": null,
      "id": 72,
      "scheduleId": 95,
      "userId": 10077,
      "status": 1,
      "name": "rep2022-03-22-17-11",
      "text": "Email report

    Knowi Team
    support@knowi.com",
      "token": null,
      "schedule": {
        "frequencyType": "days",
        "frequency": 1,
        "startTime": null,
        "cronConfig": "0 0 */1 * *",
        "id": 95,
        "type": 0,
        "host": null,
        "createdDate": null,
        "lastModDate": null,
        "sync": 0,
        "nextExecutionEpoch": 0,
        "nextExecutionTime": null
      },
      "executionReport": null,
      "accessLevel": 1,
      "timeZone": null,
      "reportType": "REPORT",
      "properties": {
        "dashboards": [
          {
            "id": 111012
          }
        ],
        "subject": "subj1",
        "sendTo": [
          "some@some.com"
        ],
        "reportAs": 10222,
        "reportContentFilters": [
          {
            "fieldName": "param1",
            "values": [
              "val1"
            ],
            "operator": "Equals",
            "type": "java.lang.String",
            "enabled": true,
            "visible": true,
            "transientFilter": false,
            "fieldType": "java.lang.String"
          },
          {
            "fieldName": "param2",
            "values": [
              "val2"
            ],
            "operator": "Equals",
            "type": "java.lang.String",
            "enabled": true,
            "visible": true,
            "transientFilter": false,
            "fieldType": "java.lang.String"
          }
        ]
      }
    }
  ]
}
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to see the list of reports
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X GET http://localhost:9090/api/1.0/reports

    View Reports

    This endpoint returns report details for a given report id

    Query

    GET /api/1.0/reports/<objectId>

    Parameter Comments
    objectId Report id to view Report
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "createdDate": 1648071581000,
  "lastModDate": null,
  "id": 72,
  "scheduleId": 95,
  "userId": 10077,
  "status": 1,
  "name": "rep2022-03-22-17-11",
  "text": "Email report

    Knowi Team
    support@knowi.com",
  "token": null,
  "schedule": {
    "frequencyType": "days",
    "frequency": 1,
    "startTime": null,
    "cronConfig": "0 0 */1 * *",
    "id": 95,
    "type": 0,
    "host": null,
    "createdDate": null,
    "lastModDate": null,
    "sync": 0,
    "nextExecutionEpoch": 0,
    "nextExecutionTime": null
  },
  "executionReport": null,
  "accessLevel": 1,
  "timeZone": null,
  "reportType": "REPORT",
  "properties": {
    "dashboards": [
      {
        "id": 111012
      }
    ],
    "subject": "subj1",
    "sendTo": [
      "some@some.com"
    ],
    "reportAs": 10222,
    "reportContentFilters": [
      {
        "fieldName": "param1",
        "values": [
          "val1"
        ],
        "operator": "Equals",
        "type": "java.lang.String",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "fieldType": "java.lang.String"
      },
      {
        "fieldName": "param2",
        "values": [
          "val2"
        ],
        "operator": "Equals",
        "type": "java.lang.String",
        "enabled": true,
        "visible": true,
        "transientFilter": false,
        "fieldType": "java.lang.String"
      }
    ]
  }
}
    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 report
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X GET http://localhost:9090/api/1.0/reports/70

    Create Report

    This endpoint is for creating a new report

    Query

    POST /api/1.0/reports/

    No parameters

    POST JSON payload:
    Sample with "Run As" (reportAs field is id of other user), and with content filters (reportContentFilters field). 
          {
        "startTime": null,
        "frequency": 1,
        "frequencyType": "days",
        "subject": "subj1",
        "name": "rep2022-03-22-17-11",
        "text": "Email report

    Knowi Team
    support@knowi.com",
        "from": null,
        "sendTo": "some@some.com",
        "cc": null,
        "bcc": null,
        "dashIds": [
          111012
        ],
        "datasets": "[]",
        "reportAs": 10222,
        "scheduleId": 90,
        "reportContentFilters": "[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]",
        "webhooks": [],
        "slacks": [],
        "teams": [],
        "executionReport": null,
        "nlpQuery": null,
        "contextPath": null,
        "nlpDatasetId": null,
        "datasetReports": null,
        "reportContentFiltersArr": null,
        "dashboards": null,
        "testRun": false
      }
    Response
    HTTP Status Response
    200 OK Output created entity
    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 create a report
  • Current user is not allowed to access specified dataset
  • Current user is not allowed to access specified dashboard
  • Not authorized to access an asset
  • Authorization exception: {exception details}
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"startTime":null,"frequency":1,"frequencyType":"days","subject":"subj1","name":"rep2022-03-22-17-11","text":"<span>Email report</span><br><br>Knowi Team<br>support@knowi.com","from":null,"sendTo":"some@some.com","cc":null,"bcc":null,"dashIds":[111012],"datasets":"[]","reportAs":10222,"scheduleId":90,"reportContentFilters":"[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]","webhooks":[],"slacks":[],"teams":[],"executionReport":null,"nlpQuery":null,"contextPath":null,"nlpDatasetId":null,"datasetReports":null,"reportContentFiltersArr":null,"dashboards":null,"testRun":false}' http://localhost:9090/api/1.0/reports

    Edit Report

    This endpoint is for updating/modifying the reports

    Query

    PUT /api/1.0/reports

    No parameters

    PUT JSON payload:
    Sample with "Run As" (reportAs field is id of other user), and with content filters (reportContentFilters field).
    Note that id of email report is within POST data as json field "emailReportId". 
          {
        "emailReportId": 68,
        "startTime": null,
        "frequency": 1,
        "frequencyType": "days",
        "subject": "subj1",
        "name": "rep1",
        "text": "Email report

    Knowi Team
    support@knowi.com",
        "from": null,
        "sendTo": "some@some.com",
        "cc": null,
        "bcc": null,
        "dashIds": [
          111012
        ],
        "datasets": "[]",
        "reportAs": 10222,
        "scheduleId": 90,
        "reportContentFilters": "[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]",
        "webhooks": [],
        "slacks": [],
        "teams": [],
        "executionReport": null,
        "nlpQuery": null,
        "contextPath": null,
        "nlpDatasetId": null,
        "datasetReports": null,
        "reportContentFiltersArr": null,
        "dashboards": null,
        "testRun": false
      }
    Response
    HTTP Status Response
    200 OK Output edited entity
    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 create report
    • 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 report
  • Not authorized to run report as another user
  • Current user is not allowed to access specified dataset
  • Current user is not allowed to access specified dashboard
  • Not authorized to access an asset
  • Authorization exception: {exception details}
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"emailReportId":68,"startTime":null,"frequency":1,"frequencyType":"days","subject":"subj1","name":"rep1","text":"<span>Email report</span><br><br>Knowi Team<br>support@knowi.com","from":null,"sendTo":"some@some.com","cc":null,"bcc":null,"dashIds":[111012],"datasets":"[]","reportAs":10222,"scheduleId":90,"reportContentFilters":"[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]","webhooks":[],"slacks":[],"teams":[],"executionReport":null,"nlpQuery":null,"contextPath":null,"nlpDatasetId":null,"datasetReports":null,"reportContentFiltersArr":null,"dashboards":null,"testRun":false}' http://localhost:9090/api/1.0/reports

    Run Report

    This endpoint is for running all the reports

    Query

    POST /api/1.0/reports/run

    No parameters

    POST JSON payload:
    Sample with "Run As" (reportAs field is id of other user), and with content filters (reportContentFilters field). 
          {
        "subject": "subj1",
        "name": "rep2022-11-22-15-54",
        "text": "Email report

    Knowi Team
    support@knowi.com",
        "from": null,
        "sendTo": "some@some.com",
        "cc": null,
        "bcc": null,
        "dashIds": [
          111012
        ],
        "datasets": "[]",
        "reportAs": 10222,
        "scheduleId": 90,
        "reportContentFilters": "[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]",
        "webhooks": [],
        "slacks": [],
        "teams": [],
        "executionReport": null,
        "nlpQuery": null,
        "contextPath": null,
        "nlpDatasetId": null,
        "datasetReports": null,
        "reportContentFiltersArr": null,
        "dashboards": null
      }
    Response
    HTTP Status Response
    200 OK Output created entity
    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 create a report
  • Current user is not allowed to access specified dataset
  • Current user is not allowed to access specified dashboard
  • Not authorized to access an asset
  • Authorization exception: {exception details}
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"subject":"subj1","name":"rep2022-11-22-15-54","text":"<span>Email report</span><br><br>Knowi Team<br>support@knowi.com","from":null,"sendTo":"some@some.com","cc":null,"bcc":null,"dashIds":[111012],"datasets":"[]","reportAs":10222,"scheduleId":90,"reportContentFilters":"[{\"fieldName\":\"param1\",\"type\":\"java.lang.String\",\"values\":[\"val1\"],\"operator\":\"Equals\"},{\"fieldName\":\"param2\",\"type\":\"java.lang.String\",\"values\":[\"val2\"],\"operator\":\"Equals\"}]","webhooks":[],"slacks":[],"teams":[],"executionReport":null,"nlpQuery":null,"contextPath":null,"nlpDatasetId":null,"datasetReports":null,"reportContentFiltersArr":null,"dashboards":null}' http://localhost:9090/api/1.0/reports/run

    Share the reports to users and groups

    This endpoint is for sharing the reports with users and groups of a given report id

    Query

    PUT /reports/<objectId>/share

    Parameter Comments
    objectId Report id to share

    POST JSON payload:

    Parameter Comments
    shareProperties Share properties json array. Available fields:
  • Type: Users, Groups.
  • accessLevel: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • ssoUser: Optional bool. Set to `true` if sharing to sso user
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com",
    "ssoUser": true
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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.
    Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"accessLevel\" : 1, \"name\" : \"some@some.com\", \"ssoUser\" : true } ] }" http://localhost:9090/api/1.0/reports/70/share

    Delete Report

    This endpoint for deleting the report of a given id

    Query

    DELETE /reports/<objectId>

    Parameter Comments
    objectId Report 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 report
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X DELETE http://localhost:9090/api/1.0/reports/68

    Alerts

    List Alerts

    This endpoint returns a listing of all alerts

    Query

    GET /api/1.0/alerts

    No parameters
    Response
    HTTP Status Response
    200 OK Output example: 
    {[
{
  "createdDate": 1648134840000,
  "lastModDate": 1648134840000,
  "id": 242,
  "datasetId": 16170,
  "lastAlert": null,
  "sendToOld": null,
  "userId": 10077,
  "alertCondition": "select * where Sent > 100",
  "dataset": {
    "createdDate": null,
    "lastModDate": null,
    "id": 16170,
    "metadataConfig": null,
    "lastUpdateDate": null,
    "mongoId": null,
    "mongoConnectUri": null,
    "customerId": 0,
    "datasetName": "test2022-02-01-19-35__3",
    "identifier": null,
    "userId": 0,
    "refreshMeta": false,
    "injectStreamTime": false,
    "nlpEnabled": true,
    "nlpBotEnabled": true,
    "nlpConfig": null,
    "customer": null,
    "metaData": null,
    "direct": false
  },
  "alertName": "alert12",
  "alertType": 4,
  "lastDataMeta": null,
  "accessLevel": 1,
  "scheduleId": 105,
  "schedule": {
    "frequencyType": "minute",
    "frequency": 15,
    "startTime": null,
    "cronConfig": "*/15 * * * *",
    "id": 105,
    "type": 0,
    "host": null,
    "createdDate": 1648134840000,
    "lastModDate": null,
    "sync": 0,
    "nextExecutionEpoch": 1648124040,
    "nextExecutionTime": 1648124040000
  },
  "realtime": true,
  "executionReport": null,
  "firedCount": 0,
  "createdBy": null,
  "deletable": true,
  "chartId": 26908,
  "lastDataMetaObj": null,
  "properties": {
    "classVersion": 2,
    "emailOutput": {
      "classVersion": 1,
      "from": "support@knowi.com",
      "sendTo": "Some@some.com",
      "cc": "",
      "bcc": "",
      "emailSubject": "alert10",
      "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
      "attachDataset": false,
      "attachResultsAfterCloud9ql": false
    },
    "webhookOutput": {
      "classVersion": 1,
      "selectedWebhooks": [
        200
      ]
    },
    "configAttachment": false,
    "attachmentConfig": {
      "datasetId": null,
      "query": ""
    },
    "alertIfNoData": false,
    "skipSameAlert": true,
    "attachAlertData": true,
    "frequencyMarker": "custom",
    "operator": ">",
    "metric": "Sent",
    "threshold": "100"
  }
}
]}
    400 BAD REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to see the list of alerts
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X GET http://localhost:9090/api/1.0/alerts

    View Alert

    This endpoint returns the alerts of a given id

    Query

    GET /api/1.0/reports/<objectId>

    Parameter Comments
    objectId Alert id to view Alert
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "createdDate": 1648134840000,
  "lastModDate": 1648134840000,
  "id": 242,
  "datasetId": 16170,
  "lastAlert": null,
  "sendToOld": null,
  "userId": 10077,
  "alertCondition": "select * where Sent > 100",
  "dataset": {
    "createdDate": null,
    "lastModDate": null,
    "id": 16170,
    "metadataConfig": null,
    "lastUpdateDate": null,
    "mongoId": null,
    "mongoConnectUri": null,
    "customerId": 0,
    "datasetName": "test2022-02-01-19-35__3",
    "identifier": null,
    "userId": 0,
    "refreshMeta": false,
    "injectStreamTime": false,
    "nlpEnabled": true,
    "nlpBotEnabled": true,
    "nlpConfig": null,
    "customer": null,
    "metaData": null,
    "direct": false
  },
  "alertName": "alert12",
  "alertType": 4,
  "lastDataMeta": null,
  "accessLevel": 1,
  "scheduleId": 105,
  "schedule": {
    "frequencyType": "minute",
    "frequency": 15,
    "startTime": null,
    "cronConfig": "*/15 * * * *",
    "id": 105,
    "type": 0,
    "host": null,
    "createdDate": 1648134840000,
    "lastModDate": null,
    "sync": 0,
    "nextExecutionEpoch": 1648124040,
    "nextExecutionTime": 1648124040000
  },
  "realtime": true,
  "executionReport": null,
  "firedCount": 0,
  "createdBy": null,
  "deletable": true,
  "chartId": 26908,
  "lastDataMetaObj": null,
  "properties": {
    "classVersion": 2,
    "emailOutput": {
      "classVersion": 1,
      "from": "support@knowi.com",
      "sendTo": "Some@some.com",
      "cc": "",
      "bcc": "",
      "emailSubject": "alert10",
      "emailBody": "Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%",
      "attachDataset": false,
      "attachResultsAfterCloud9ql": false
    },
    "webhookOutput": {
      "classVersion": 1,
      "selectedWebhooks": [
        200
      ]
    },
    "configAttachment": false,
    "attachmentConfig": {
      "datasetId": null,
      "query": ""
    },
    "alertIfNoData": false,
    "skipSameAlert": true,
    "attachAlertData": true,
    "frequencyMarker": "custom",
    "operator": ">",
    "metric": "Sent",
    "threshold": "100"
  }
}
    400 BAD REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to access specified alert
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X GET http://localhost:9090/api/1.0/alerts/232

    Create Alert

    There can be multiple different input options and is not possible to list all of them here. Please create alerts in UI and then read JSON with View or List endpoints to see alert structure and learn the options available.

    Query

    POST /api/1.0/alerts/

    No parameters

    POST JSON payload:
    Sample alert creation for widget alert with alert action as Email and Webhook: 
            {
          "alertId": 0,
          "chartId": 26908,
          "alertName": "alert12",
          "alertType": "4",
          "alertDatasetIds": [
            16170
          ],
          "alertCondition": null,
          "jsonConfig": "{\"operator\":\">\",\"metric\":\"Sent\",\"threshold\":\"100\",\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":true,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"from\":\"support@knowi.com\",\"sendTo\":\"Some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"alert10\",\"emailBody\":\"Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false},\"webhookOutput\":{\"classVersion\":1,\"selectedWebhooks\":[200]}}",
          "frequency": 15,
          "frequencyType": "minute",
          "startTime": null,
          "realtime": true,
          "drilldownChain": "26908"
        }

    Sample alert creation for dataset as trigger notification with action to Email: 
            {
          "alertId": 0,
          "chartId": null,
          "alertName": "alertTrigger10",
          "alertType": "1",
          "alertDatasetIds": [
            16170
          ],
          "alertCondition": "select * where sample > 100",
          "jsonConfig": "{\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":false,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"sendTo\":\"some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"Subject\",\"from\":\"\",\"emailBody\":\"Dataset %DATASET_NAME% alert condition has been been triggered by query:
    \\n%ALERT_CONDITION%
    \\n
    \\nKnowi Team
    \\nsupport@knowi.com\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false}}",
          "frequency": 100,
          "frequencyType": "minute",
          "startTime": "03/24/2022 10:52+03:00",
          "realtime": false,
          "drilldownChain": null
        }
    Response
    HTTP Status Response
    200 OK Outputs the created Alert entity.
    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 create alert
    • 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 create alert
    • Example

    Sample alert creation for widget alert with alert action as Email and Webhook:

     curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"alertId":0,"chartId":26908,"alertName":"alert12","alertType":"4","alertDatasetIds":[16170],"alertCondition":null,"jsonConfig":"{\"operator\":\">\",\"metric\":\"Sent\",\"threshold\":\"100\",\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":true,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"from\":\"support@knowi.com\",\"sendTo\":\"Some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"alert10\",\"emailBody\":\"Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false},\"webhookOutput\":{\"classVersion\":1,\"selectedWebhooks\":[200]}}","frequency":15,"frequencyType":"minute","startTime":null,"realtime":true,"drilldownChain":"26908"}' http://localhost:9090/api/1.0/alerts

    Sample alert creation for dataset as trigger notification with action to Email:

    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"alertId":0,"chartId":null,"alertName":"alertTrigger10","alertType":"1","alertDatasetIds":[16170],"alertCondition":"select * where sample > 100","jsonConfig":"{\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":false,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"sendTo\":\"some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"Subject\",\"from\":\"\",\"emailBody\":\"Dataset %DATASET_NAME% alert condition has been been triggered by query:<br>\\n<span style=\\\"padding-left:25px;font-style: italic;\\\">%ALERT_CONDITION%</span><br>\\n<br>\\nKnowi Team<br>\\nsupport@knowi.com\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false}}","frequency":100,"frequencyType":"minute","startTime":"03/24/2022 10:52+03:00","realtime":false,"drilldownChain":null}' http://localhost:9090/api/1.0/alerts

    Edit Alert

    This endpoint is for updating/modifying the alerts

    Query

    PUT /api/1.0/alerts

    No parameters

    PUT JSON payload:
    Sample dataset trigger alert edit:.
    Note that id of alert to edit is within POST data as json field "alertId". 
          {
        "alertId": 232,
        "chartId": null,
        "alertName": "alertTrigger13b",
        "alertType": "1",
        "alertDatasetIds": [
          16170
        ],
        "alertCondition": "select * where sample > 100",
        "jsonConfig": "{\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":false,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"sendTo\":\"some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"Subject\",\"from\":\"\",\"emailBody\":\"Dataset %DATASET_NAME% alert condition has been been triggered by query:
    \\n%ALERT_CONDITION%
    \\n
    \\nKnowi Team
    \\nsupport@knowi.com\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false}}",
        "frequency": 100,
        "frequencyType": "minute",
        "startTime": "03/24/2022 10:52+03:00",
        "realtime": false,
        "drilldownChain": null
      }
    Response
    HTTP Status Response
    200 OK Output example: 
    Output edited entity.
    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 create report
    • 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 alert
    • Example

    Sample dataset trigger alert edit:

    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X PUT -d '{"alertId":232,"chartId":null,"alertName":"alertTrigger13b","alertType":"1","alertDatasetIds":[16170],"alertCondition":"select * where sample > 100","jsonConfig":"{\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":false,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"sendTo\":\"some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"Subject\",\"from\":\"\",\"emailBody\":\"Dataset %DATASET_NAME% alert condition has been been triggered by query:<br>\\n<span style=\\\"padding-left:25px;font-style: italic;\\\">%ALERT_CONDITION%</span><br>\\n<br>\\nKnowi Team<br>\\nsupport@knowi.com\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false}}","frequency":100,"frequencyType":"minute","startTime":"03/24/2022 10:52+03:00","realtime":false,"drilldownChain":null}' http://localhost:9090/api/1.0/alerts

    Share to Users and Groups

    This endpoint is for sharing the alerts with users and groups of a given alert id

    Query

    PUT /alerts/lt;objectId>/share

    Parameter Comments
    objectId Alert id to share

    PUT JSON payload:

    Parameter Comments
    shareProperties Share properties json array. Available fields:
  • Type: Users, Groups.
  • accessLevel: 1 - Edit rights, 2 - Read-only
  • name: the name of the User to share to
  • ssoUser: Optional bool. Set to `true` if sharing to sso user
  • id: group id of the Group to share to.
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com",
    "ssoUser": true
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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.
    Example

    curl -i -H "Authorization: Bearer HEREISYOUR_BEARER" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"accessLevel\" : 1, \"name\" : \"a@a.com\", \"ssoUser\" : true } ] }" http://localhost:9090/api/1.0/alerts/232/share

    Delete Alert

    This endpoint is for deleting a alert of a given alert id

    Query

    DELETE /alerts/<objectId>

    Parameter Comments
    objectId Alert 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 alert
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X DELETE http://localhost:9090/api/1.0/alerts/232

    Test Run Alert

    Run the alert (provided as input json, not via ID) as a test with executing alert actions. Useful to check alert before creating (saving) it.

    Query

    POST /api/1.0/alerts/test

    No parameters

    POST JSON payload:
    Sample alert creation for widget alert with alert action as Email and Webhook: 
            {
          "alertId": 240,
          "chartId": 26908,
          "alertName": "alert12",
          "alertType": "4",
          "alertDatasetIds": [
            16170
          ],
          "alertCondition": null,
          "jsonConfig": "{\"operator\":\">\",\"metric\":\"Sent\",\"threshold\":\"100\",\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":true,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"from\":\"support@knowi.com\",\"sendTo\":\"Some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"alert10\",\"emailBody\":\"Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false},\"webhookOutput\":{\"classVersion\":1,\"selectedWebhooks\":[200]}}",
          "frequency": 15,
          "frequencyType": "minute",
          "startTime": null,
          "realtime": true,
          "drilldownChain": "26908"
        }
    Response
    HTTP Status Response
    200 OK Output contains JSON with details of alert test, including alert actions status.
    Output example: 
    {"executionDate":1648110509606,"executionStatus":"ALERT","duration":723,"details":[{"ok":true,"channel":"EMAIL","error":"Sent"},{"ok":false,"channel":"WEBHOOK","error":"Unable to execute webhook url http://url1.com due to unexpected error, please contact the administrator."}]}
    In this example output the email sent fine, the webhook failed.
    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 alert
    • Example

    Sample: run alert and send to email and webhook. 

    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"alertId":240,"chartId":26908,"alertName":"alert12","alertType":"4","alertDatasetIds":[16170],"alertCondition":null,"jsonConfig":"{\"operator\":\">\",\"metric\":\"Sent\",\"threshold\":\"100\",\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":true,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"from\":\"support@knowi.com\",\"sendTo\":\"Some@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"alert10\",\"emailBody\":\"Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false},\"webhookOutput\":{\"classVersion\":1,\"selectedWebhooks\":[200]}}","frequency":15,"frequencyType":"minute","startTime":null,"realtime":true,"drilldownChain":"26908"}' http://localhost:9090/api/1.0/alerts/test

    Preview Widget Alert

    Applicable only for anomaly detection widget alert type.

    Output the temporary widget bean with properties and with preview data for alert.

    Query

    POST /api/1.0/alerts/preview/widget

    No parameters

    POST JSON payload:
    Sample input: 
            {
          "alertId": 234,
          "chartId": 26908,
          "alertName": "alert10",
          "alertType": "5",
          "alertDatasetIds": [
            16170
          ],
          "alertCondition": null,
          "jsonConfig": "{\"operator\":\">\",\"metric\":\"Sent\",\"dateTime\":\"Week\",\"threshold\":\"100\",\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":true,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"from\":\"support@knowi.com\",\"sendTo\":\"Test8@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"alert10\",\"emailBody\":\"Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false}}",
          "frequency": 15,
          "frequencyType": "minute",
          "startTime": null,
          "realtime": true,
          "drilldownChain": "26908"
        }
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "createdDate": null,
  "lastModDate": null,
  "id": -1,
  "name": "Polynomial Regression Model",
  "userId": 0,
  "customerId": 0,
  "datasetId": 0,
  "type": 1,
  "description": null,
  "urlString": null,
  "access": 0,
  "refreshChartMillis": -1,
  "jsonConfig": null,
  "shareUrl": null,
  "accessLevel": -1,
  "dashboardAccessLevel": -1,
  "categoryAccessLevel": -1,
  "autoShared": false,
  "urlShareWhitelistDomain": null,
  "filterSettings": null,
  "chartType": null,
  "alertCount": 0,
  "queryId": -1,
  "queryStr": null,
  "adhocQuery": null,
  "categories": null,
  "userExternalAuthId": 0,
  "userSso": false,
  "drilldown": false,
  "dataset": null,
  "position": {
    "chartId": 0,
    "width": 500,
    "height": 400,
    "originalScreenWidth": 0,
    "originalScreenHeight": 0,
    "col": 0,
    "row": 0,
    "ypos": 0,
    "xpos": 0,
    "id": 0,
    "size_x": 0,
    "size_y": 0
  },
  "associations": null,
  "queryModified": false,
  "updateFilters": false,
  "dataFields": [
    "id",
    "Sent",
    "message_type",
    "Customer",
    "Week",
    "Date",
    "Opened",
    "Spam",
    "Bounced",
    "Delivered",
    "Clicks",
    "Conversions",
    "Campaign_name"
  ],
  "dataFieldsTypes": {
    "id": "java.lang.Integer",
    "Sent": "java.lang.Integer",
    "message_type": "java.lang.String",
    "Customer": "java.lang.String",
    "Week": "java.util.Date",
    "Date": "java.util.Date",
    "Opened": "java.lang.Integer",
    "Spam": "java.lang.Integer",
    "Bounced": "java.lang.Integer",
    "Delivered": "java.lang.Integer",
    "Clicks": "java.lang.Integer",
    "Conversions": "java.lang.Integer",
    "Campaign_name": "java.lang.String"
  },
  "transientChartFilters": null,
  "typeModified": false,
  "lastSyncDate": null,
  "viewOnly": false,
  "truncated": null,
  "processedName": "Polynomial Regression Model",
  "processedDescription": null,
  "processedFootNote": null,
  "error": null,
  "widgetConfig": null,
  "notDefaultFilter": false,
  "chartProperties": {
    "chart.type": "anomaly",
    "chart.anomaly.dimension": "",
    "chart.anomaly.threshold": "100",
    "chart.anomaly.algorithm": "Polynomial Regression Model",
    "chart.xAxis.column": "Week",
    "chart.series.data": "Sent"
  },
  "xAxis": null,
  "yAxis": null,
  "dataJSONArr": [
    {
      "name": "Sent",
      "id": "Sent",
      "data": [
        {
          "name": 1423382400000,
          "x": 1423382400000,
          "y": 1682348
        },
        {
          "name": 1423987200000,
          "x": 1423987200000,
          "y": 33593964
        },
        {
          "name": 1424592000000,
          "x": 1424592000000,
          "y": 2753792
        }
      ],
      "type": "line",
      "zIndex": "0",
      "zoneAxis": "x",
      "color": "#E61BCB",
      "chart.anomaly.dimension": null
    },
    {
      "name": "Boundaries",
      "id": "Boundaries",
      "data": [
        {
          "name": 1423382400000,
          "x": 1423382400000,
          "low": 0,
          "high": 3364696
        },
        {
          "name": 1423987200000,
          "x": 1423987200000,
          "low": 0,
          "high": 67187928
        },
        {
          "name": 1424592000000,
          "x": 1424592000000,
          "low": 0,
          "high": 5507584
        }
      ],
      "type": "arearange",
      "zIndex": "1",
      "lineWidth": "0",
      "linkedTo": "previous",
      "fillOpacity": "0.12",
      "color": "#FF8682",
      "chart.anomaly.dimension": null
    }
  ],
  "chartMarkers": null,
  "dataGroup": null,
  "gridBean": null,
  "xaxisJSONArr": null,
  "yaxisJSONArr": null,
  "filters": [],
  "widgetAccessLevel": -1,
  "chartPropertiesNullOrEmpty": false,
  "filterFieldDataTypes": {},
  "processedFilters": [],
  "live": false,
  "dataDisplayTypes": {},
  "dbFields": [
    "id",
    "Sent",
    "message_type",
    "Customer",
    "Week",
    "Date",
    "Opened",
    "Spam",
    "Bounced",
    "Delivered",
    "Clicks",
    "Conversions",
    "Campaign_name"
  ],
  "ignoreVals": [
    "id",
    "Sent",
    "message_type",
    "Customer",
    "Week",
    "Date",
    "Opened",
    "Spam",
    "Bounced",
    "Delivered",
    "Clicks",
    "Conversions",
    "Campaign_name"
  ],
  "widgetTypeStr": "chart",
  "filterFieldDataTypesIncludingNested": {}
}
    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 preview widget alert
    • 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 alert
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"alertId":234,"chartId":26908,"alertName":"alert10","alertType":"5","alertDatasetIds":[16170],"alertCondition":null,"jsonConfig":"{\"operator\":\">\",\"metric\":\"Sent\",\"dateTime\":\"Week\",\"threshold\":\"100\",\"classVersion\":2,\"frequencyMarker\":\"custom\",\"alertIfNoData\":false,\"skipSameAlert\":true,\"configAttachment\":false,\"attachmentConfig\":{\"datasetId\":null,\"query\":\"\"},\"attachAlertData\":true,\"emailOutput\":{\"classVersion\":1,\"from\":\"support@knowi.com\",\"sendTo\":\"Test8@some.com\",\"cc\":\"\",\"bcc\":\"\",\"emailSubject\":\"alert10\",\"emailBody\":\"Alert triggered: %ALERT_HUMAN_READABLE_CONDITION%\",\"attachDataset\":false,\"attachResultsAfterCloud9ql\":false}}","frequency":15,"frequencyType":"minute","startTime":null,"realtime":true,"drilldownChain":"26908"}' http://localhost:9090/api/1.0/alerts/preview/widget

    Preview Alert Data

    This endpoint returns the preview of a alert data of a given alert id

    Query

    POST /api/1.0/alerts/lt;objectId>/preview/data

    Parameter Comments
    objectId Alert id to preview the data

    POST JSON payload:
    Contains additional parameters (the c9QL and datasetId).
    Sample input: 
            {"c9QL":"select * where Sent > 100","datasetId":16170}
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "jsonRows": [
    {
      "Sent": 255621,
      "message_type": "Transactional",
      "Customer": "Facebook",
      "Week": "02/27/2015 00:00:00 PST",
      "Date": "01/28/2015 16:29:00 PST",
      "Opened": 65935,
      "Spam": 602,
      "Bounced": 15242,
      "Delivered": 237103,
      "Clicks": 16073,
      "Conversions": 3121,
      "Campaign_name": "Trial",
      "id ": 81754,
      "id": 1
    },
    {
      "Sent": 235279,
      "message_type": "Transactional",
      "Customer": "Target",
      "Week": "02/27/2015 00:00:00 PST",
      "Date": "02/28/2015 16:29:00 PST",
      "Opened": 51505,
      "Spam": 564,
      "Bounced": 12779,
      "Delivered": 210054,
      "Clicks": 13115,
      "Conversions": 2569,
      "Campaign_name": "Newsletter",
      "id ": 81755,
      "id": 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:
  • Failed to preview alert data
    • 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 alert
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" -X POST -d '{"c9QL":"select * where Sent > 100","datasetId":16170}' http://localhost:9090/api/1.0/alerts/242/preview/data

    Status of Alert

    This endpoint returns the status and history of a given triggering alert id

    Query

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

    Parameter Comments
    objectId Alert id to view status
    Response
    HTTP Status Response
    200 OK Output example: 
    [
  {
    "executionDate": 1648114321000,
    "executionStatus": "ALERT",
    "duration": 55,
    "details": [
      {
        "ok": true,
        "channel": "EMAIL",
        "error": "Sent"
      }
    ]
  },
  {
    "executionDate": 1648120329000,
    "executionStatus": "ALERT",
    "duration": 32,
    "details": [
      {
        "ok": true,
        "channel": "EMAIL",
        "error": "Sent"
      }
    ]
  }
]
    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 alert
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/json" http://localhost:9090/api/1.0/alerts/239/status

    Actions

    Actions can be used in Alerts and Email Reports.

    NOTE: In the ManagementAPI creation and edit of Slack and Teams actions is not supported. Please use UI for that and then List that actions to get id and use to create/edit Alerts and Email Reports.

    List

    Output list of actions for specified type. Type (the last path parameter) can be either webhook, slack or teams.

    Query

    GET /api/1.0/action/<actionType>

    Parameter Comments
    actionType Type of actions to list. Possible values: webhook, slack or teams.
    Response
    HTTP Status Response
    200 OK Output example: 
    {
  "list": [
    {
      "createdDate": 1490490365000,
      "lastModDate": 1490524068000,
      "id": 157,
      "userId": 10077,
      "actionType": "WEBHOOK",
      "jsonConfig": "{\"classVersion\":1,\"url\":\"url1z\",\"authUrl\":\"\",\"authHeaders\":\"\",\"webhookHeaders\":\"\",\"name\":\"name1\"}",
      "classVersion": 1,
      "url": "url1z",
      "authUrl": "",
      "authHeaders": "",
      "webhookHeaders": "",
      "name": "name1"
    }
  ]
}
    400 BAD REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
    Error details:
  • Wrong type paramete
    • 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" -H "Content-Type: application/json" http://localhost:9090/api/1.0/action/webhook

    Create (only webhook)

    This endpoint is for creating a new webhook

    Query

    POST /api/1.0/action/webhook

    No parameters

    POST JSON payload:

    Sample input: 
            {
          "classVersion": 1,
          "url": "http://some3.com",
          "authUrl": "http://auth",
          "authHeaders": "",
          "webhookHeaders": "header1:val1",
          "name": "name1"
        }
    Response
    HTTP Status Response
    200 OK Output created entity
    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" -H "Content-Type: application/json" -X POST -d '{"classVersion":1,"url":"http://some3.com","authUrl":"http://auth","authHeaders":"","webhookHeaders":"header1:val1","name":"name1"}' http://localhost:9090/api/1.0/action/webhook

    Edit (only webhook)

    This Endpoint is for updating/modifying a webhook of a given webhook id

    Query

    PUT /api/1.0/action/lt;actionType>/lt;objectId>

    Parameter Comments
    actionType Type of action to edit. Possible values: webhook, slack or teams.
    objectId Action id to edit
    Response
    HTTP Status Response
    200 OK Output edited entity
    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" -H "Content-Type: application/json" -X PUT -d '{"classVersion":1,"url":"http://some3new.com","authUrl":"http://auth","authHeaders":"","webhookHeaders":"header1:val1","name":"name1"}' http://localhost:9090/api/1.0/action/webhook/202

    Datasources

    List Datasources

    This endpoint is for returning a listing of all the datasources

    Query

    GET /api/1.0/datasources

    No parameters
    Response
    HTTP Status Response
    200 OK Output example: 
    {
   "list":[
      {
         "createdDate":1492025827000,
         "lastModDate":1492060895000,
         "strId":"hXlIbZ",
         "op":2,
         "connectorAssignee":null,
         "connectorSyncStatus":1,
         "lastSyncDate":null,
         "connector":null,
         "id":3144,
         "name":"\"someName\"",
         "datasource":"mongo",
         "userId":10077,
         "customerId":1033,
         "connectorId":1,
         "accessLevel":1
      }
   ]
}
    NOTE: from entity output excluded the "jsonConfig" field.
    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/datasources

    Get Datasource

    This endpoint is for returning a datasource of a given datasource id

    Query

    GET /api/1.0/datasources/<datasourceId>

    Parameter Comments
    datasourceId Datasource ID to view
    Response
    HTTP Status Response
    200 OK Output example: 
    {
   "createdDate":1492025827000,
   "lastModDate":1492060895000,
   "strId":"hXlIbZ",
   "op":2,
   "connectorAssignee":null,
   "connectorSyncStatus":1,
   "lastSyncDate":null,
   "connector":null,
   "id":3144,
   "name":"\"someName\"",
   "datasource":"mongo",
   "userId":10077,
   "customerId":1033,
   "connectorId":1,
   "accessLevel":1
}
    NOTE: from entity output excluded the "jsonConfig" field.
    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 datasource
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/datasources/123

    Create Datasource

    This endpoint is for creating a new datasource

    Query

    POST /api/1.0/datasources/

    POST JSON payload. 

    
  
    SubfieldTypeDescription
       
  
    nameStringDatasource name
       
  
    datasourceStringDatasource type: bigquery, cloud9charts, cloudant, couchbase, datastax, elasticsearch, ga, hana, hive, influxdb, logsene, marklogic, mongo, mysql, omniture, oracle, orientdb, phoenix, postgresql, presto, salesforce, redshift, restapi, snowflake, spark, sqlserver, teradata
              
  
    privateConnectorNumberID of private connector (only if "privateDatasource" field is set to true)
          
  
    privateDatasourceBooleantrue if this datasource is using private connector; false otherwise
       
  
    tunnelAddressStringSSH tunnel connect string in the form of cloud9@<tunnel-host>:@<tunnel-port>
      

  
    Standard datasource properties
    
  
    dataverseString(couchbase) Dataverse which should only be set for Couchbase Analytics
    
  
    dbNameString(cloudant, couchbase, datastax, hana, hive, influxdb, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Database, Bucket, or Keyspace name
       
  
    dbPropertiesString(datastax, elasticsearch, hana, hive, marklogic, mongo, mysql, oracle, postgresql, presto, redshift, snowflake, spark, sqlserver) Database specific properties in datasource specific format such as headers, query string, etc
    
  
    hostString(couchbase, datastax, hana, hive, influxdb, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Database host(s)
    
  
    passwordString(cloudant, couchbase, datastax, elasticsearch, hana, hive, influxdb, logsene, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, restapi, snowflake, spark, sqlserver, teradata) User password
      
  
    portNumber(datastax, hana, hive, marklogic, mongo, mysql, oracle, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Database port
      
  
    urlString(cloudant, elasticsearch, logsene, restapi) Database URL
      
  
    userIdString(cloudant, couchbase, datastax, elasticsearch, hana, hive, influxdb, logsene, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, restapi, snowflake, spark, sqlserver, teradata) User ID
      
  
    schemaString(hana, hive, mysql, oracle, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Schema name
     
  
    warehouseString(snowflake) Snowflake warehouse
    

  
    OAuth datasource properties
    
  
    authRefreshTokenString(bigquery, ga, salesforce) OAuth refresh token
    
  
    authTokenString(bigquery, ga, salesforce) OAuth token
     
  
    projectIdString(bigquery) Project ID
      
  
    gaProfileIDString(ga) Google analytic profile ID
     
  
    sfInstanceURLString(salesforce) Salesforce instance URL
               

  
    Other datasource properties
    
  
    authHeadersString(restapi) REST auth headers
    
  
    authEndPointString(restapi) REST auth endpoint
    
  
    authPostPayloadString(restapi) REST auth POST payload
    
  
    authUrlParamsString(restapi) REST URL
    Example: 
    {
   "name":"Mongo Database Test",
   "host":"some.host.com",
   "port":10642,
   "dbName":"someDbName",
   "userId":"someUserId",
   "password":"somePwd12345",
   "dbProperties":"",
   "privateDatasource":false,
   "privateConnector":479,
   "tunnel":false,
   "tunnelAddress":"",
   "datasource":"mongo"
}
    Response
    HTTP Status Response
    200 OK Return created Datasource json info (same as "Get Datasource" command). Output example: 
    {
   "createdDate":1492025827000,
   "lastModDate":1492060895000,
   "strId":"hXlIbZ",
   "op":2,
   "connectorAssignee":null,
   "connectorSyncStatus":1,
   "lastSyncDate":null,
   "connector":null,
   "id":3144,
   "name":"\"someName\"",
   "datasource":"mongo",
   "userId":10077,
   "customerId":1033,
   "connectorId":1,
   "accessLevel":1
}
    NOTE: from entity output excluded the "jsonConfig" field.
    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 processing properties to create new datasource - 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
    • 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 "{\"name\":\"Mongo Database Test\", \"host\":\"some.host.com\", \"port\":10642, \"dbName\":\"someDbName\", \"userId\":\"someUserId\", \"password\":\"somePwd12345\", \"dbProperties\":\"\", \"privateDatasource\": false, \"privateConnector\":479, \"tunnel\":false, \"tunnelAddress\":\"\", \"datasource\":\"mongo\"}" http://localhost:9090/api/1.0/datasources

    Edit Datasource

    This endpoint is for updating/modifying a datasource of a given datasource id

    Query

    PUT /api/1.0/datasources/<objectId>

    Parameter Comments
    objectId ID of Datasource to edit

    PUT JSON payload. 

    
  
    SubfieldTypeDescription
       
  
    nameStringDatasource name
       
  
    datasourceStringDatasource type: bigquery, cloud9charts, cloudant, couchbase, datastax, elasticsearch, ga, hana, hive, influxdb, logsene, marklogic, mongo, mysql, omniture, oracle, orientdb, phoenix, postgresql, presto, salesforce, redshift, restapi, snowflake, spark, sqlserver, teradata
              
  
    privateConnectorNumberID of private connector (only if "privateDatasource" field is set to true)
          
  
    privateDatasourceBooleantrue if this datasource is using private connector; false otherwise
       
  
    tunnelAddressStringSSH tunnel connect string in the form of cloud9@<tunnel-host>:@<tunnel-port>
      

  
    Standard datasource properties
    
  
    dataverseString(couchbase) Dataverse which should only be set for Couchbase Analytics
    
  
    dbNameString(cloudant, couchbase, datastax, hana, hive, influxdb, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Database, Bucket, or Keyspace name
       
  
    dbPropertiesString(datastax, elasticsearch, hana, hive, marklogic, mongo, mysql, oracle, postgresql, presto, redshift, snowflake, spark, sqlserver) Database specific properties in datasource specific format such as headers, query string, etc
    
  
    hostString(couchbase, datastax, hana, hive, influxdb, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Database host(s)
    
  
    passwordString(cloudant, couchbase, datastax, elasticsearch, hana, hive, influxdb, logsene, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, restapi, snowflake, spark, sqlserver, teradata) User password
      
  
    portNumber(datastax, hana, hive, marklogic, mongo, mysql, oracle, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Database port
      
  
    urlString(cloudant, elasticsearch, logsene, restapi) Database URL
      
  
    userIdString(cloudant, couchbase, datastax, elasticsearch, hana, hive, influxdb, logsene, marklogic, mongo, mysql, oracle, orientdb, phoenix, postgresql, presto, redshift, restapi, snowflake, spark, sqlserver, teradata) User ID
      
  
    schemaString(hana, hive, mysql, oracle, phoenix, postgresql, presto, redshift, snowflake, spark, sqlserver, teradata) Schema name
     
  
    warehouseString(snowflake) Snowflake warehouse
    

  
    OAuth datasource properties
    
  
    authRefreshTokenString(bigquery, ga, salesforce) OAuth refresh token
    
  
    authTokenString(bigquery, ga, salesforce) OAuth token
     
  
    projectIdString(bigquery) Project ID
      
  
    gaProfileIDString(ga) Google analytic profile ID
     
  
    sfInstanceURLString(salesforce) Salesforce instance URL
               
  
    Other datasource properties
    
  
    authHeadersString(restapi) REST auth headers
    
  
    authEndPointString(restapi) REST auth endpoint
    
  
    authPostPayloadString(restapi) REST auth POST payload
    
  
    authUrlParamsString(restapi) REST URL
    Example: 
    {
   "name":"Mongo Database Test",
   "host":"some.host.com",
   "port":10642,
   "dbName":"someDbName",
   "userId":"someUserId",
   "password":"somePwd12345",
   "dbProperties":"",
   "privateDatasource":false,
   "privateConnector":479,
   "tunnel":false,
   "tunnelAddress":"",
   "datasource":"mongo"
}
    Response
    HTTP Status Response
    200 OK Return edited Datasource json info (same as "Get Datasource" command). Output example: 
    {
   "createdDate":1492025827000,
   "lastModDate":1492060895000,
   "strId":"hXlIbZ",
   "op":2,
   "connectorAssignee":null,
   "connectorSyncStatus":1,
   "lastSyncDate":null,
   "connector":null,
   "id":3144,
   "name":"\"someName\"",
   "datasource":"mongo",
   "userId":10077,
   "customerId":1033,
   "connectorId":1,
   "accessLevel":1
}
    NOTE: from entity output excluded the "jsonConfig" field.
    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 datasource - 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 datasource
    • 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\":\"Mongo Database Test\", \"host\":\"some.host.com\", \"port\":10642, \"dbName\":\"someDbName\", \"userId\":\"someUserId\", \"password\":\"somePwd12345\", \"dbProperties\":\"\", \"privateDatasource\": false, \"privateConnector\":479, \"tunnel\":false, \"tunnelAddress\":\"\", \"datasource\":\"mongo\"}"  http://localhost:9090/api/1.0/datasources/123

    Delete Datasource

    This endpoint is for deleting a datasource of a given datasource id

    Query

    DELETE /api/1.0/datasources/<objectId>

    Parameter Comments
    objectId Id of Datasource 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 datasource
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://localhost:9090/api/1.0/datasources/123

    Share Datasource to Users/Groups

    This endpoint is for sharing the datasources with users and groups of a given datasource id

    Query

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

    Parameter Comments
    objectId Id of Datasource to share
    ssoUser Optional bool. Set to `true` if sharing to sso user

    PUT JSON payload:

    Parameter Comments
    shareProperties JSON array of objects 
    
  
    SubfieldTypeDescription
          
  
    typeStringShare type: Users or Groups
       
  
    accessLevelNumber1 = Edit rights
    2 = Read-only
       
  
    nameStringName of the user to share to
       
  
    idNumberGroup id of the group to share to
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com" 
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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 edit specified datasource
    • 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\", \"accessLevel\" : 1, \"name\" : \"someUser@host.com\" } ] }"  http://localhost:9090/api/1.0/datasources/110643/share

    Clone Datasource

    This endpoint is for cloning the datasource of a given datasource id

    Query

    POST /api/1.0/datasources/<objectIdToClone>

    Parameter Comments
    objectIdToClone Datasource id of Datasource to clone

    POST JSON payload:

    Parameter Comments
    datasourceName New (cloned) Name of Datasource
    Response
    HTTP Status Response
    200 OK Return cloned Datasource json info (same as "Get Datasource" command). Output example: 
    {
   "createdDate":1492025827000,
   "lastModDate":1492060895000,
   "strId":"hXlIbZ",
   "op":2,
   "connectorAssignee":null,
   "connectorSyncStatus":1,
   "lastSyncDate":null,
   "connector":null,
   "id":3144,
   "name":"\"someName\"",
   "datasource":"mongo",
   "userId":10077,
   "customerId":1033,
   "connectorId":1,
   "accessLevel":1
}
    NOTE: from entity output excluded the "jsonConfig" field.
    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 datasource - more details at server log
  • Missed datasourceName 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 datasource
    • 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" -d "{\"datasourceName\":\"newName\"}"  http://localhost:9090/api/1.0/datasources/12345

    Queries

    List Queries

    This endpoint returns all the queries

    Query

    GET /api/1.0/queries

    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":1492400077000,
         "lastModDate":1492400077000,
         "jsonConfig":"{\n  \"entityName\" : \"test123\",\n  \"queryStr\" : \"db[someTable].find().limit(10000)\",\n  \"datasourceId\" : 1427,\n  \"discovery\" : {\n    \"tableName\" : \"someTable\",\n    \"limit\" : 10000\n  },\n  \"direct\" : false,\n  \"triggered\" : false,\n  \"overrideVals\" : {\n    \"replaceAll\" : true\n  }\n}",
         "strId":"pvH8wk",
         "op":1,
         "connectorSyncStatus":1,
         "id":2017,
         "entityName":"test123",
         "datasourceId":1427,
         "userId":10077,
         "customerId":1033,
         "queryStr":"db[someTable].find().limit(10000)",
         "identifier":"kVrQip",
         "status":0,
         "triggerDatasetId":0,
         "discovery":{
            "tableName":"someTable",
            "limit":10000
         },
         "accessLevel":1,
         "triggered":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 category filter parameters
    • 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/queries?byCategory=123,642

    Get Query

    This endpoint returns the queries of a given query id

    Query

    GET /api/1.0/queries/<queryId>?loadJoinDataSources=true

    Parameter Comments
    queryId Query ID (integer) to view or Query Identifier (string)
    loadJoinDataSources Optional query parameter. If set to true, then also joined Queries will be loaded associated with selected query/td>
    Response
    HTTP Status Response
    200 OK Output example: 
    {
   "createdDate":1492400077000,
   "lastModDate":1492400077000,
   "lastUpdateDate":1538086002000,
   "jsonConfig":"{\n  \"entityName\" : \"test123\",\n  \"queryStr\" : \"db[someTable].find().limit(10000)\",\n  \"datasourceId\" : 1427,\n  \"discovery\" : {\n    \"tableName\" : \"someTable\",\n    \"limit\" : 10000\n  },\n  \"direct\" : false,\n  \"triggered\" : false,\n  \"overrideVals\" : {\n    \"replaceAll\" : true\n  }\n}",
   "strId":"pvH8wk",
   "op":1,
   "connectorSyncStatus":1,
   "id":2017,
   "entityName":"test123",
   "datasourceId":1427,
   "userId":10077,
   "customerId":1033,
   "queryStr":"db[someTable].find().limit(10000)",
   "identifier":"kVrQip",
   "status":0,
   "triggerDatasetId":0,
   "discovery":{
      "tableName":"someTable",
      "limit":10000
   },
   "accessLevel":1,
   "triggered":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 query
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER"  http://localhost:9090/api/1.0/queries/123

    Create Query

    This endpoint is for creating a new query

    Query

    POST /api/1.0/queries/

    POST JSON payload:

    Parameter Comments
    runNow boolean -- True to save and run query
    properties JSON properties 
    
  
    SubfieldTypeDescription
          
  
    categoriesStringComma seperated list of 1 or more categories
       
  
    c9QLFilterStringC9QL query
       
  
    datasourceIdNumberDatasource ID
       
  
    directBooleanIs direct query
    
  
    entityNameStringQuery name
     
  
    frequencyNumberSchedule frequency
      
  
    frequencyTypeStringSchedule frequency type: minute, hours, 
      

  
    joinQueriesArrayArray of <JoinQuery> type objects
         
  
    <JoinQuery>.c9QLFilterStringC9QL query
      
  
    <JoinQuery>.datasourceIdNumberDatasource ID
           
  
    <JoinQuery>.joinKeysMapMap of join key fields where for each entry of the map, key represents the left handside fieldname and value represents right handside fieldname.
     
  
    <JoinQuery>.joinTypeStringJoin type: BLEND, INNER JOIN, OUTER JOIN, LEFT OUTER JOIN, RIGHT OUTER JOIN, LOOP JOIN
     
  
    <JoinQuery>.queryStrStringDatasource specific proprietary query
    
  
    overrideValsStringOverride strategy which can be:
    1. <Empty>: append mode
    2. "All": replace all
    3. <Comma seperated list of 1 or more fields>: replace based on combination of fields
    
  
    queryStrStringDatasource specific proprietary query
      
  
    startTimeStringSchedule start time time which can be in one of the following formats:
        MM-dd-yyyy HH:mm:ssXXX
        MM-dd-yyyy HH:mm:ss
        MM/dd/yyyy HH:mm:ssXXX
        MM/dd/yyyy HH:mm:ss
        MM/dd/yyyy HH:mmXXX
        MM/dd/yyyy HH:mm
        MM/dd/yy HH:mm:ssXXX
        MM/dd/yy HH:mm:ss
        MM/dd/yy HH:mmXXX
        MM/dd/yy HH:mm
        MM/dd/yyyyXXX
        MM/dd/yyyy
        MM/dd/yyXXX
        MM/dd/yy
        HH:mm:ssXXX
        HH:mm:ss
        HH:mmXXX
        HH:mm
        mmXXX
        mm
    
  
    triggeredBooleanIs triggered query
      
  
    c9ExportDatasetNumber(cloud9charts) Source dataset ID
    Example: 
    {
   "entityName":"test123",
   "queryStr":"db['someTable'].find().limit(10000)",
   "c9QLFilter":"",
   "datasourceId":1427,
   "datasource":"mongo",
   "dsName":"LocalMongo",
   "direct":false,
   "triggered":false,
   "overrideVals":"All"
}
    Response
    HTTP Status Response
    200 OK Output example: 
    {
   "createdDate":1492400077000,
   "lastModDate":1492400077000,
   "jsonConfig":"{\n  \"entityName\" : \"test123\",\n  \"queryStr\" : \"db[someTable].find().limit(10000)\",\n  \"datasourceId\" : 1427,\n  \"discovery\" : {\n    \"tableName\" : \"someTable\",\n    \"limit\" : 10000\n  },\n  \"direct\" : false,\n  \"triggered\" : false,\n  \"overrideVals\" : {\n    \"replaceAll\" : true\n  }\n}",
   "strId":"pvH8wk",
   "op":1,
   "connectorSyncStatus":1,
   "id":2017,
   "entityName":"test123",
   "datasourceId":1427,
   "userId":10077,
   "customerId":1033,
   "queryStr":"db[someTable].find().limit(10000)",
   "identifier":"kVrQip",
   "status":0,
   "triggerDatasetId":0,
   "discovery":{
      "tableName":"someTable",
      "limit":10000
   },
   "accessLevel":1,
   "triggered":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:
  • Missed properties field
  • Error processing properties to create new query - 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
    • 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 "{\"properties\":{\"entityName\":\"test123\", \"queryStr\":\"db['someTable'].find().limit(10000)\", \"c9QLFilter\":\"\", \"datasourceId\":1427, \"datasource\":\"mongo\", \"dsName\":\"LocalMongo\", \"direct\":false, \"triggered\":false, \"overrideVals\":\"All\"} }" http://localhost:9090/api/1.0/queries

    Refresh Query

    This endpoint is for refreshing the queries of a given id

    Query

    POST /api/1.0/queries/<queryId>/refreshQuery

    Parameter Comments
    queryId ID of query to be refreshed
    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 refreshing query - 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 refresh specified query
    • 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" -X POST http://localhost:9090/api/1.0/queries/20038/refreshQuery

    Edit Query

    This endpoint is for updating/modifying the query of a given query id

    Query

    PUT /api/1.0/queries/<queryId>

    Parameter Comments
    queryId ID of query to be edited

    POST JSON payload:

    ParameterComments
    properties JSON properties 
    
  
    SubfieldTypeDescription
          
  
    categoriesStringComma seperated list of 1 or more categories
       
  
    c9QLFilterStringC9QL query
       
  
    datasourceIdNumberDatasource ID
       
  
    directBooleanIs direct query
    
  
    entityNameStringQuery name
     
  
    frequencyNumberSchedule frequency
      
  
    frequencyTypeStringSchedule frequency type: minute, hours, 
      

  
    joinQueriesArrayArray of <JoinQuery> type objects
         
  
    <JoinQuery>.c9QLFilterStringC9QL query
      
  
    <JoinQuery>.datasourceIdNumberDatasource ID
           
  
    <JoinQuery>.joinKeysMapMap of join key fields where for each entry of the map, key represents the left handside fieldname and value represents right handside fieldname.
     
  
    <JoinQuery>.joinTypeStringJoin type: BLEND, INNER JOIN, OUTER JOIN, LEFT OUTER JOIN, RIGHT OUTER JOIN, LOOP JOIN
     
  
    <JoinQuery>.queryStrStringDatasource specific proprietary query
    
  
    overrideValsStringOverride strategy which can be:
    1. <Empty>: append mode
    2. "All": replace all
    3. <Comma seperated list of 1 or more fields>: replace based on combination of fields
    
  
    queryStrStringDatasource specific proprietary query
      
  
    startTimeStringSchedule start time time which can be in one of the following formats:
        MM-dd-yyyy HH:mm:ssXXX
        MM-dd-yyyy HH:mm:ss
        MM/dd/yyyy HH:mm:ssXXX
        MM/dd/yyyy HH:mm:ss
        MM/dd/yyyy HH:mmXXX
        MM/dd/yyyy HH:mm
        MM/dd/yy HH:mm:ssXXX
        MM/dd/yy HH:mm:ss
        MM/dd/yy HH:mmXXX
        MM/dd/yy HH:mm
        MM/dd/yyyyXXX
        MM/dd/yyyy
        MM/dd/yyXXX
        MM/dd/yy
        HH:mm:ssXXX
        HH:mm:ss
        HH:mmXXX
        HH:mm
        mmXXX
        mm
    
  
    triggeredBooleanIs triggered query
      
  
    c9ExportDatasetNumber(cloud9charts) Source dataset ID
    Example: 
    {
   "entityName":"test123",
   "queryStr":"db['someTable'].find().limit(10000)",
   "c9QLFilter":"",
   "datasourceId":1427,
   "datasource":"mongo",
   "dsName":"LocalMongo",
   "direct":false,
   "triggered":false,
   "overrideVals":"All"
}
    Response
    HTTP StatusResponse
    200 OK Output example: 
    {
   "createdDate":1492400077000,
   "lastModDate":1492400077000,
   "jsonConfig":"{\n  \"entityName\" : \"test123\",\n  \"queryStr\" : \"db[someTable].find().limit(10000)\",\n  \"datasourceId\" : 1427,\n  \"discovery\" : {\n    \"tableName\" : \"someTable\",\n    \"limit\" : 10000\n  },\n  \"direct\" : false,\n  \"triggered\" : false,\n  \"overrideVals\" : {\n    \"replaceAll\" : true\n  }\n}",
   "strId":"pvH8wk",
   "op":1,
   "connectorSyncStatus":1,
   "id":2017,
   "entityName":"test123",
   "datasourceId":1427,
   "userId":10077,
   "customerId":1033,
   "queryStr":"db[someTable].find().limit(10000)",
   "identifier":"kVrQip",
   "status":0,
   "triggerDatasetId":0,
   "discovery":{
      "tableName":"someTable",
      "limit":10000
   },
   "accessLevel":1,
   "triggered":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:
  • Missed properties field
  • Error processing properties to create new query - 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
    • 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 "{\"properties\":{\"entityName\":\"test123\", \"queryStr\":\"db['someTable'].find().limit(10000)\", \"c9QLFilter\":\"\", \"datasourceId\":1427, \"datasource\":\"mongo\", \"dsName\":\"LocalMongo\", \"discovery\":{\"tableName\":\"someTable\", \"metrics\":[], \"dimensions\":[], \"sort\":[], \"limit\":10000, \"filters\":[], \"datasourceId\":1427, \"datasource\":\"mongo\", \"dsName\":\"LocalMongo\"}, \"direct\":false, \"triggered\":false, \"overrideVals\":\"All\"} }"  http://localhost:9090/api/1.0/queries/20050

    Delete Query

    This endpoint is for deleting a query of a given query id

    Query

    DELETE /api/1.0/queries/<queryId>

    Parameter Type Comments
    queryId Integer ID of query to be deleted
    removeWidgets Boolean Delete any associated widgets
    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 deleting query - 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 query
    • 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" -X DELETE http://localhost:9090/api/1.0/queries/20038

    Share Query to Users/Groups

    This endpoint is for sharing the queries with users and groups of a given query id

    Query

    PUT /api/1.0/queries/<queryId>/query

    Parameter Comments
    queryId Id of Query to edit
    ssoUser Optional bool. Set to `true` if sharing to sso user

    JSON PUT payload:

    Parameter Comments
    shareProperties JSON array of objects 
    
  
    SubfieldTypeDescription
          
  
    typeStringShare type: Users or Groups
       
  
    accessLevelNumber1 = Edit rights
    2 = Read-only
       
  
    nameStringName of the user to share to
       
  
    idNumberGroup id of the group to share to
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com" 
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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 edit specified query
    • 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\", \"accessLevel\" : 1, \"name\" : \"someUser@host.com\" } ] }"  http://localhost:9090/api/1.0/queries/105530

    Clone Query

    This endpoint is for cloning a query of a given query id

    Query

    POST /api/1.0/queries/<objectIdToClone>

    Parameter Comments
    objectIdToClone Query id of Query to clone

    POST JSON payload:

    Parameter Comments
    clonedQueryName New (cloned) Name of Query
    Response
    HTTP Status Response
    200 OK Return cloned Query json info (same as "Get Query" command). Output example: 
    {
   "createdDate":1492400077000,
   "lastModDate":1492400077000,
   "jsonConfig":"{\n  \"entityName\" : \"test123\",\n  \"queryStr\" : \"db[someTable].find().limit(10000)\",\n  \"datasourceId\" : 1427,\n  \"discovery\" : {\n    \"tableName\" : \"someTable\",\n    \"limit\" : 10000\n  },\n  \"direct\" : false,\n  \"triggered\" : false,\n  \"overrideVals\" : {\n    \"replaceAll\" : true\n  }\n}",
   "strId":"pvH8wk",
   "op":1,
   "connectorSyncStatus":1,
   "id":2017,
   "entityName":"test123",
   "datasourceId":1427,
   "userId":10077,
   "customerId":1033,
   "queryStr":"db[someTable].find().limit(10000)",
   "identifier":"kVrQip",
   "status":0,
   "triggerDatasetId":0,
   "discovery":{
      "tableName":"someTable",
      "limit":10000
   },
   "accessLevel":1,
   "triggered":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:
  • Error cloning query - more details at server log
  • Missed clonedQueryName 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 query
    • 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 "{\"clonedQueryName\":\"newName123\"}"  http://localhost:9090/api/1.0/queries/12345

    Categories

    List Categories

    This endpoint is for returning all the categories

    Query

    GET /api/1.0/category?objectType=<objectType>

    Parameter Comments
    objectType Type of categories to list. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)
    withSharing Optional, value (boolean) true/false. Default value is false. If true, then output will contain sharing information to which users and/or groups each category is shared
    Response
    HTTP Status Response
    200 OK Output example: 
    {
   "list":[
      {
         "createdDate":null,
         "lastModDate":null,
         "userId":10077,
         "id":16,
         "parentId":0,
         "ownerUserName":"someUser@host.com",
         "accessLevel":1,
         "name":"name2"
      }
   ]
}
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

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

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

    Error details:
  • Current user is not allowed to see the list of categories
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" <Add the URL here>

    Share Category to Users/Groups

    This endpoint is for sharing the categories with users and groups of a given category id

    Query

    PUT /api/1.0/category/<objectId>/share?objectType=<objectType>

    Parameter Comments
    objectId Category id of Category to share
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    PUT JSON payload:

    Parameter Comments
    shareProperties Share properties json array. Available fields:
  • Type: Users, Groups.
  • accessLevel: 1 - Edit rights, 2 - Read-only, 5 - Deny (Exclude).
  • name: the name of the User to share to
  • id: group id of the Group to share to.
    • ssoUser Optional bool. Set to `true` if sharing to sso user
    Example: 
    [ 
  { 
    "type" : "Users", 
    "accessLevel" : 1, 
    "name" : "someUser1@host.com",
    "ssoUser" : true
  },
  { 
    "type" : "Groups", 
    "accessLevel" : 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 accessLevel field
  • shareProperties has invalid the type value
  • shareProperties has invalid the accessLevel 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 category
    • 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 $bearer" -H "Content-Type: application/json" -X PUT -d "{\"shareProperties\" : [ { \"type\" : \"Users\", \"access_level\" : 1, \"name\" : \"shaunSSO@knowi.com\",  \"ssoUser\" : true} ] }"  "https://www.knowi.com/api/1.0/category/13993/share?objectType=1"

    Create Category

    This endpoint is for creating a new category

    Query

    POST /api/1.0/category?objectType=<objectType>

    Parameter Comments
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    POST JSON payload:

    Parameter Comments
    parentId Id of a parent category. Set 0 to make the root category
    categoryName Name of new category
    Response
    HTTP Status Response
    200 OK Return created Category json info. Output example: 
    {
         "createdDate":1481572146000,
         "lastModDate":null,
         "userId":10077,
         "id":16,
         "parentId":0,
         "ownerUserName":"someUser@host.com",
         "accessLevel":1,
         "name":"name2"
}
    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 parentId field
  • Invalid categoryName field
  • Category name is empty
    • 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 create a category
  • Have no rights to add into parent category
    • 409 CONFLICT 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Error details:
  • Provided category 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 "{\"parentId\":123,\"categoryName\":\"new name\"}" "https://www.knowi.com/api/1.0/category?objectType=2"

    Delete Category

    This endpoint is for deleting the categories of a given category id

    Query

    DELETE /api/1.0/category/<objectId>?objectType=<objectType>

    Parameter Comments
    objectId Category id of category to delete
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)
    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 category - 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 a category
  • No rights to delete selected category
  • Error removing category - more details at server log
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X DELETE http://www.knowi.com/api/1.0/category/105?objectType=2

    Edit Category

    This endpoint is for updating/modifying a category of a given category id

    Query

    PUT /api/1.0/category/<objectId>?objectType=<objectType>

    Parameter Comments
    objectId Category id of category to edit
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    PUT JSON payload:

    Parameter Comments
    categoryName New name of category
    parentId New parent Id of category
    Response
    HTTP Status Response
    200 OK Return edited Category json info. Output example: 
    {
         "createdDate":1481572146000,
         "lastModDate":null,
         "userId":10077,
         "id":16,
         "parentId":0,
         "ownerUserName":"someUser@host.com",
         "accessLevel":1,
         "name":"name2"
}
    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 parentId field
  • Missed categoryName field
  • Category name is empty
  • Parent id should not equal current object id
    • 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 category
  • No rights to edit this category
  • No rights to add into parent category
    • 409 CONFLICT 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Error details:
  • New category name already exists in destination parent category
    • 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 "{\"categoryName\":\"updated category name\", \"parentId\": 123}" http://www.knowi.com/api/1.0/category/105?objectType=2

    Assign Asset to Categories

    This endpoint is for assigning the assets to the categories

    Query

    POST /api/1.0/category/assign?objectType=<objectType>

    Parameter Comments
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    POST JSON payload:

    Parameter Comments
    objectId Asset id to assign categories to. This could be Dashboard id, Widget id or Query id, depending on objectType parameter.
    categories Array of categories IDs to assign (replace).
    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 objectId field
  • Missed categories field
  • Invalid object type
    • 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 category
  • No rights to asset
    • 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 "{\"objectId\":10050, \"categories\": [ 123, 456 ] }" http://www.knowi.com/api/1.0/category/assign?objectType=2

    Add category to asset

    This endpoint is for adding a category with asset

    Query

    POST /api/1.0/category/add?objectType=<objectType>

    Parameter Comments
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    POST JSON payload:

    Parameter Comments
    objectId Asset id to add category to. This could be Dashboard id, Widget id or Query id, depending on objectType parameter.
    category Id of category to add.
    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 object type
  • Missed objectId field
  • Missed category 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 a category
  • No rights to asset
  • No rights to edit this category
    • 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 "{ \"objectId\":10050, \"category\":123 }" http://www.knowi.com/api/1.0/category/add?objectType=2

    Remove category from asset

    This category is for removing the categories from assets

    Query

    POST /api/1.0/category/remove?objectType=<objectType>

    Parameter Comments
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    POST JSON payload:

    Parameter Comments
    objectId Asset id to remove category from. This could be Dashboard id, Widget id or Query id, depending on objectType parameter.
    category Id of category to remove.
    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 object type
  • Missed objectId field
  • Missed category 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 a category
  • No rights to asset
  • No rights to edit this category
    • 404 NOT FOUND 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Error details:
  • No category to delete
    • 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 "{ \"objectId\":10050, \"category\":123 }" http://www.knowi.com/api/1.0/category/remove?objectType=2

    Copy a category

    Copies category structure from source category to a destination category including assets association. The assets will not be cloned, only put into a new category structure.

    Query

    POST /api/1.0/category/copy?objectType=<objectType>

    Parameter Comments
    objectType Type of categories. Possible values: 1 (Dashboards), 2 (Charts), 4 (Queries)

    POST JSON payload:

    Parameter Comments
    objectId Asset id to add category to. This could be Dashboard id, Widget id or Query id, depending on objectType parameter.
    sourceCategoryId Source category id to copy from
    targetParentCategoryId Target category id to which put the copy of source category
    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 sourceCategoryId field
  • Missed targetParentCategoryId field
  • Error removing category - 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 a category
  • No rights to copy source category
  • No edit rights to paste into destination category
    • 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 "{ \"sourceCategoryId\":10050, \"targetParentCategoryId\":10025 }" http://www.knowi.com/api/1.0/category/copy?objectType=2

    NLP

    The NLP API lets you develop applications to list query suggestions and retrieve the associated response from the query. With this API, you can make NLP requests to search across datasets within a given user's account.

    The result of NLP query is a JSON object that includes query suggestions with matching datasetId or the parsed results from the NLP query.

    List suggestions

    Get query suggestions with keyword searches

    GET /api/1.0/nlp/suggestions?query=average

    Parameter Comments
    query Query which will be used for generation of autosuggestions
    Response
    HTTP Status Response
    200 OK Output example: 
    [
    {
        "query": "average conversions",
        "datasetId": "16042",
        "datasetName": "report 2"
    },
    {
        "query": "average spam",
        "datasetId": "16041",
        "datasetName": "report 1"
    },
    {
        "query": "average unitprice",
        "datasetId": "16037",
        "datasetName": "Online_Retail_2"
    },
    {
        "query": "average customerid",
        "datasetId": "16036",
        "datasetName": "Online_Retail_1"
    },
    {
        "query": "average opened",
        "datasetId": "16042",
        "datasetName": "report 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
    		•
    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": "Current user is not allowed to use natural language processing",
    "documentation_url": "https://www.knowi.com/docs/managementAPI.html"
}

    Common error details:
  • Current user is not allowed to use natural language processing
    		•
    Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -X GET "http://localhost:9090/api/1.0/nlp/suggestions?query=aver"

    Parse suggestion

    Returns results of parsed NLP query

    Query

    POST /api/1.0/nlp/query/parse

    Parameter Required Comments
    query Yes Query to process
    datasetId Yes Dataset that your query relates to
    format Yes Format of the response (json, txt). Defaults to json
    Response
    HTTP Status Response
    200 OK Output example: 
    [
    {
        "Average Conversions": 3295.814814814815
    }
]
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Something went wrong during the nlp processing
    		•
    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": "Current user is not allowed to use natural language processing",
    "documentation_url": "https://www.knowi.com/docs/managementAPI.html"
}

    Common error details:
  • Current user is not allowed to use natural language processing
    		•
    Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/x-www-form-urlencoded" -d "datasetId=16040&query=average%20conversions&format=json" "http://localhost:9090/api/1.0/nlp/query/parse"

    NLP across dataset

    Returns results of parsed NLP query with best match dataset.

    Query

    POST /api/1.0/nlp/dataset

    POST JSON payload:

    Parameter Required Comments
    query Yes Query to process
    Response
    HTTP Status Response
    200 OK Output example: 
    {      
    "data":[
      {
          "sent": 100
      },
      {
          "sent": 200
      }
    ],
    "datasetName":"csv157",
    "datasetId":15532"
}
    204 NO_CONTENT 
    {
    "message": "No datasets found to match query",
    "documentation_url": "https://www.knowi.com/docs/managementAPI.html"
}

    Error details:
  • Current user is not allowed to use natural language processing
    		•
    400 BAD_REQUEST 
    { "message": <Error details>, "documentation_url": <Documentation link> }

    Error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Something went wrong during the nlp processing
    		•
    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
    Error details:
  • Current user is not allowed to use natural language processing
    		•
    500 INTERNAL_SERVER_ERROR
    Error details:
  • Failed to generate json output
    		•
    Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" -H "Content-Type: application/x-www-form-urlencoded" -d "query=show%20where%20sending_activity%20grater%20than%20100" http://localhost:9090/api/1.0/nlp/dataset

    Datasets

    Get data

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

    Query

    GET /api/1.0/datasets

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

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

    Common error details:
  • Bearer token is not found or expired
  • Authorization issue or user does not exist
    • Example
    curl -i -H "Authorization: Bearer HERE_IS_YOUR_BEARER" 
"http://localhost:9090/api/1.0/datasets?identifier=eQzNis&
runtimeTokens=%5B%7B%22parameterName%22%3A%22%24c9_hitsParam%24%22%2C%20%22parameterValue%22%3A3%7D%5D"

    View (Get Dataset Info)

    This endpoint returns the dataset of a given dataset id

    Query

    GET /api/1.0/datasets/<objectId>

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

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

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

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

    Delete the Dataset

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

    Query: Delete the dataset with dataset_id paremeter

    curl -i -X DELETE -H "Authorization: Bearer <token>" http://localhost:9090/api/1.0/datasets/<dataset_id>

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

    Query: Delete the dataset with datasetnameurl_encoded parameter

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

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

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

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

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

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

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

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

    InstantSights

    Query: To get intant sights by widget-id as a parameter

    curl -i -X GET -H "Authorization: Bearer e0Z3DIqtdurha2gzeqMKXg2Kvf4ipY5Sl13JrolDoOrwie" 'http://localhost:9090/api/1.0/widgets/<widget-id>/insights'
    Parameter Comments
    widget-id widget-id to view the widget

    Response:

    [
{
"insight":{

  "id":"com.knowi.anomalyGrowthByDate",
  "name":"Anomaly Growth By Date",
  "description":"Calculate and return any anomaly detected for the growth by date",
  "category":"Anomaly"
},
"output":[
  "-0.92% change for Close that occurred on 14 Mar 23 is below than the normal ranges.",
  "2.62% change for Close that occurred on 13 Mar 23 is above than the normal ranges."
]
},
{
"insight":{

  "id":"com.knowi.growthLatestByDate",
  "name":"Latest Growth By Date",
  "description":"Show latest growth summary information",
  "category":"Growth"
},
"output":[
  "The growth rate for Close during the latest period is -0.92% occurred on 14 Mar 23"
]
},
{
"insight":{

  "id":"com.knowi.growthLatestByGroup",
  "name":"Latest Growth By Group",
  "description":"Show latest growth summary information",
  "category":"Growth"
},
"output":[
  "The growth rate for Close during the latest period is -1.29% occurred for Apple on 14 Mar 23"
]
},
{
"insight":{

  "id":"com.knowi.growthTopByDate",
  "name":"Top Growth By Date",
  "description":"Show where growth of numeric value is highest by date",
  "category":"Growth"
},
"output":[
  "The top growth rate for Close is 11.06% occurred on 09 Nov 22"
]
},
{
"insight":{

  "id":"com.knowi.growthTopByGroup",
  "name":"Top Growth By Group",
  "description":"Show where growth of numeric value is highest by group",
  "category":"Growth"
},
"output":[
  "The top growth rate for Close is 19.64% occurred for Tesla on 08 Mar 21"
]
}
]

    AI Summary

    Generates AI Summary based on the Instant Insights for a widget.

    Query: To get instant insights

    GET /insights/aiSummary

    Parameter Comments
    Context Context is an optional parameter allowing users to add instructions in plain text to filter/enhance the response.
    Response
    HTTP Status Response
    200 OK 
        {
    [
      {
   "summary": " Based on the provided data, here are the key insights:\n\n "Delivered":\nThe delivered value of 2,087,404 on Date 08 Jul 14 was below the predicted low threshold of 2,345,131.5.\n\n "Opened":\nThe growth rate for Opened during the latest period was 76.54%, which occurred on Date 09 Jul 14. The top growth rate for Opened was also 76.54%, which occurred on the same date.\n\n"Sent":\nThere were 11 records for Sent, with an average of 3,941,661.27, a minimum value of 2,295,850, a maximum value of 6,459,369, a standard deviation of 1,150,823.61, and a median of 3,491,998.\n\n"Clicks":\nThere were 11 records for Clicks, with an average of 178,997.45, a minimum value of 88,406, a maximum value of 297,139, a standard deviation of 59,517.37, and a median of 156,880."
      }
    ]
  }
    Example
    curl -i -X GET -H "Authorization: Bearer nKQW1W9aNE34TgBpJ0cXIgHlhD6Ble6Insjvip6h68iisie" 'http://knowi.com/api/1.0/widgets/26275/insights/aiSummary'

    AI Set Suggestions

    Sets suggestions automatically using the AI engine.

    Query: Sets suggestions based on the widget ID

    POST /insights/aiSetSuggestions

    Response
    HTTP Status Response
    200 OK Successful
    Example
    curl -i -X PUT -H "Authorization: Bearer nKQW1W9aNE34TgBpJ0cXIgHlhD6Ble6Insjvip6h68iisie" 'http://knowi.com/api/1.0/widgets/26275/insights/aiSuggestions'

    System Status

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

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

    Check all components

    This Endpoint returns and check all the components

    Query

    Returns the status of all components

    GET /api/1.0/kpi

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

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

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

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

    Check specific component

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

    Query

    GET /api/1.0/kpi/<component>

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

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

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

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