Category API

This article describes API calls to configure Categories:

  • /api/category: Allows retrieving, creating, updating, and deleting a Category.

Prerequisites:

  • Set up API access
  • Verify that you have API access and obtain a token via get_token call
  • Beginning v7.1.0 Power Users must be granted the Create Categories and Subcategories privilege to create Categories.
  • The Power User must have edit access to a Category to be able to update and delete it.

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Configure Categories
    1. Retrieve Categories
    2. Create Category
    3. Update Category
    4. Delete Category

1. Access Admin > System > API Toolkit

2. Configure Categories

2.1. Retrieve Categories

The GET request to /api/category returns all Categories.

  1. Item: category
  2. Method: GET
  3. Optionally, filter the result by the Category ID:
    • ID: The ID of the Category
      • category_id
  4. Enter an API Token
  5. [Run request]

Example Response 

{
  "categories": [
    {
      "id": 86,
      "name": "Administration",
      "parent_category_id": null,
      "description": "",
      "visible_on_dashboard": "Y",
      "visible_in_search": "Y",
      "business_owner_id": 19,
      "technical_owner_id": 19,
      "sort_order_owner_id": 19,
      "access_request_email": "[email protected]",
      "use_custom_access_denied_message": "Y",
      "access_denied_message": "<p style=\"text-align: center;\">category message</p>"
    },
    {
      "id": 84,
      "name": "Connection Test",
      "parent_category_id": 86,
      "description": "",
      "visible_on_dashboard": "Y",
      "visible_in_search": "Y",
      "business_owner_id": 19,
      "technical_owner_id": 19,
      "sort_order_owner_id": 19,
      "access_request_email": null,
      "use_custom_access_denied_message": "N",
      "access_denied_message": null
    }
  ]
}

Field Description

Parameter Name Value Type Description
id integer The ID of the Category
name string The name of the Category
parent_category_id integer The ID of the parent Category
description string The description of the Category
visible_on_dashboard string Whether or not the Category is visible on the homepage. Supported values: "Y", "N".
visible_in_search string Whether or not the Category is visible in Search. Supported values: "Y", "N".
business_owner_id integer The ID of the Category Business Owner.
technical_owner_id integer The ID of the Category Technical Owner.
sort_order_owner_id integer The ID of the User who set the sort order.
access_request_email string The email to which access requests are sent.
use_custom_access_denied_message string Whether or not the custom Access denied message is enabled. Supported values: "Y", "N".
access_denied_message string The Category's Access denied message.
  • NOTE: This parameter will work only if use_custom_access_denied_message is set to 'Y'

2.2. Create Category

The POST request to /api/category creates a new Category.

  1. Item: category
  2. Method: POST
  3. ID: Enter the ID of an existing Document
  4. Select JSON request and modify the request body by providing the following values:
    • name: The name of the Category
    • visible_on_dashboard: Whether or not the Category is visible on the homepage.
      • Supported values: "Y", "N".
    • visible_in_search: Whether or not the Category is visible in Search.
      • Supported values: "Y", "N".
    • sort_order_owner_id: The ID of the User who set the sort order.
    • access_request_email: The email to which access requests are sent.
    • use_custom_access_denied_message: Whether or not the custom Access denied message is enabled.
      • Supported values: "Y", "N".
    • access_denied_message: The Category's Access denied message.
      • NOTE: This parameter will work only if use_custom_access_denied_message is set to "Y"
    • business_owner_id: The ID of the Category Business Owner.
    • technical_owner_id: The ID of the Category Technical Owner.
  5. Enter an API Token
  6. [Run request]

2.3. Update Category

The PUT request to /api/category/id/<ID> creates a new Category.

  1. Item: category
  2. Method: POST
  3. ID: Enter the ID of the Category that needs to be updated.
  4. Select JSON request and modify the request body by providing the following values:
    • id: The ID of the Category that needs to be updated
    • name: The name of the Category
    • visible_on_dashboard: Whether or not the Category is visible on the homepage.
      • Supported values: "Y", "N".
    • visible_in_search: Whether or not the Category is visible in Search.
      • Supported values: "Y", "N".
    • sort_order_owner_id: The ID of the User who set the sort order.
    • access_request_email: The email to which access requests are sent.
    • use_custom_access_denied_message: Whether or not the custom Access denied message is enabled.
      • Supported values: "Y", "N".
    • access_denied_message: The Category's Access denied message.
      • NOTE: This parameter will work only if use_custom_access_denied_message is set to "Y"
    • business_owner_id: The ID of the Category Business Owner.
    • technical_owner_id: The ID of the Category Technical Owner.
  5. Enter an API Token
  6. [Run request]

2.4. Delete Category

The DELETE request to /api/category/id/<ID> deletes the selected Category.

  1. Item: category
  2. Method: DELETE
  3. ID: Enter the ID of the Category that needs to be deleted
  4. Enter an API Token
  5. [Run request]