What can we help you with?

e.g. Getting Started, Build Dashboards

Top

Category Management

Follow

Categories

List Categories

This endpoint is for returning all the categories

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. The default value is false. If true, then the output will contain sharing information to which users and/or groups each category is shared
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
 
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

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.
  • access_level: 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.
sso_user

Optional bool. Set to `true` if sharing with the sso user.

Example:

[
  {
     "type": "Users",
     "access_level": 1,
     "name": "someUser1@host.com",
     "ssoUser": true
  },
  {
    "type": "Groups",
    "access_level": 1,
    "id": 10001
  }
]
HTTP Status Response
200 OK No response body
400 BAD_REQUEST 
{ "message": <Error details>, "documentation_url": <Documentation link> }

Common error details:
  • Missing Authorization header
  • Invalid count of Authorization headers
  • Bearer token missing
  • Error details:
  • Missed shareProperties field
  • shareProperties missed the type field
  • shareProperties missed the access_level field
  • shareProperties has invalid the type value
  • shareProperties has invalid the access_level value
  • shareProperties missed the id field
  • shareProperties missed the name field
  • shareProperties has invalid the name field
401 UNAUTHORIZED 
{ "message": <Error details>, "documentation_url": <Documentation link> }

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

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

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
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
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
  • Current user does not 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. 
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)
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 removing category - more details at server log Error details:
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
  • Current user does not have rights to delete selected category
 
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
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
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
  • Current user does not have rights to edit this category
  • Current user does not have rights to add into this 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. 
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).
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 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 a category
  • Current user does not have rights to edit this category
  • Current user does not have 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. 
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.
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. 
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

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.
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. 
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
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
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. 
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
Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles