Categories

When you start using the Management API, the first step is to create an API-managed category and obtain its unique category ID.

• The category must be identified by name or ID when adding URLs and IP addresses.
• You can add URLs and IP addresses only to API-managed categories. An attempt to use another category (that is, a Master Database category or custom category created via the Forcepoint Security Manager) is considered an error, which causes the request to fail.

API-managed categories may include the following attributes:

• Name (required): When creating an API-managed category, you must give it a unique, alphanumeric name.
  • The name cannot contain any of the following characters:

    * < > { } ~ ! $ % & @ # . " | \ & + = ? / ; : ,

  • The category name and ID must be unique within the deployment. An API- managed category cannot be given the same name as an existing Forcepoint- defined or custom category.
  • The category name appears in the Forcepoint Security Manager and in reports.
  • You may specify either the category name or ID (see below) to add, delete, modify, or view URLs and IP addresses.
• ID (required): When you create an API-managed category, it is automatically assigned a unique ID.
  • The ID is a number with a value of 1899 or higher.
  • After committing a transaction, use the list categories command to find each new API-managed category’s unique ID (see List API-managed categories or all categories).
• Description (optional): The category description, if any, appears both in the Security Manager and in the response to the API call used to view the category. It may contain alphanumeric characters, periods, and commas. It cannot include any of the following characters:

  * < > { } ~ ! $ % & @ # " | \ & + = ? / ; :

• Level (optional): When you add an API-managed category, you can also define a parent category.
  • If the parent category does not exist, it is added along with the child category.
  • If not otherwise defined, the parent category is assigned the default value of 0 (Miscellaneous).

    Up to two levels of subcategory may be added under Miscellaneous. For example:

    Miscellaneous

    First_Level_Child_Category

    Second_Level_Child_Category

    The Miscellaneous category is a Forcepoint-defined category that cannot be changed.

If administrators attempt to add URLs or IP addresses to anything other than an API- managed category, a 400 (bad request) error is returned. This indicates that the category name or ID is invalid because it:

• Does not exist
• Belongs to a Forcepoint-defined category
• Belongs to a custom category defined via the Security Manager