This API enables customers to generate a bearer access token to call the Custom Categories API.
Authentication
Requests to the Token Management API require an API token (api-key-string) to be passed in the header.
To generate this API token, go to the Platform Services > Admin in the Web Security Cloud and
click the Generate API Token.
Now that the api-key-string has been generated, a bearer access token can be created using the
Generate bearer access token endpoint.
Generate a bearer access token that can be used for authorization purpose.
Token Validity: The generated bearer access token is valid for 59 minutes after creation.
X-API-KEY required | string Example: api-key-string In this header you will have to pass your api key |
{- "token": "token-string"
}
This API enables customers to manage Custom Categories
via API endpoints instead of the portal.
Audience
This API guide is intended for:
- Developers who integrate and manage Custom Categories via API endpoints instead of using the portal.
- Software Engineers responsible for implementing API-based automation within their organization.
- System Administrators who configure and maintain API access for managing Custom Categories.
Authentication
All requests to the Custom Category API require authentication using bearer access tokens.
Clients must include a valid bearer access token in the Authorization header of each request.
Example Header:
Authorization: Bearer YOUR_BEARER_ACCESS_TOKEN
To obtain a bearer access token, see the Token Management Public API.
API path to retrieve all custom categories for the account.
cursor | string Cursor for pagination |
import requests def get_categories( url:str, headers, next_page_cursor: str = "" ) -> object: """Get all categories.""" querystring = {"cursor": next_page_cursor} response = requests.request( "GET", url, data="", headers=headers, params=querystring, ) print(response.text) return response token = "" # Insert bearer access token here next_page_cursor = "" # Insert nextPageCursor value from previous response here (OPTIONAL: Leave empty string) host = "https://ws-custom-categories.api.forcepoint.io" api_version = "1.0.0" headers = {"Authorization": f"Bearer {token}"} url = f"{host}/v{api_version}" get_categories(url, headers, next_page_cursor)
{- "totalResults": 0,
- "nextPageCursor": "string",
- "categories": [
- {
- "id": 0,
- "name": "no name",
- "description": "string",
- "policyName": "string"
}
]
}
API path to create a new custom category for the account.
name required | string |
description | string |
sites | Array of strings <= 30000 items List of website URLs and IP addresses |
policyName | string |
comment | string Comment field appears in "Get Transaction Status" response, not in Cloud Web portal |
{- "name": "string",
- "description": "string",
- "sites": [
- "string"
], - "policyName": "string",
- "comment": "string"
}
{- "transactionId": "00000000-0000-0000-0000-000000000000",
- "status": "pending",
- "data": { },
- "comment": "string"
}
API path to retrieve the number of sites, number of custom categories, site limits and custom category limits for the account.
import requests def get_limits(url:str, headers:object) -> object: """Get number of sites, number of custom categories, site limits and custom category limits.""" response = requests.request( "GET", url, data="", headers=headers, ) print(response.text) return response token = "" # Insert bearer access token here host = "https://ws-custom-categories.api.forcepoint.io" api_version = "1.0.0" headers = {"Authorization": f"Bearer {token}"} url = f"{host}/v{api_version}/limits" get_limits(url, headers)
{- "customCategoryCount": 1,
- "customCategoryUrlCount": 1,
- "customCategoryLimit": 1,
- "customCategoryUrlLimit": 1
}
API path to retrieve the details of a specific custom category by providing its ID.
categoryId required | integer ID of category to return |
cursor | string Cursor for pagination |
import requests def get_category_by_id( url:str, headers, next_page_cursor: str = "" ) -> object: """Get category by id.""" querystring = {"cursor": next_page_cursor} response = requests.request( "GET", url, data="", headers=headers, params=querystring, ) print(response.text) return response token = "" # Insert bearer access token here category_id = 0 # Insert category id here next_page_cursor = "" # Insert nextPageCursor value from previous response here (OPTIONAL: Leave empty string) host = "https://ws-custom-categories.api.forcepoint.io" api_version = "1.0.0" headers = {"Authorization": f"Bearer {token}"} url = f"{host}/v{api_version}/{category_id}" get_category_by_id(url, headers, next_page_cursor)
{- "id": 0,
- "name": "no name",
- "description": "string",
- "sites": [
- {
- "totalResults": 0,
- "nextPageCursor": "string",
- "values": [
- "string"
]
}
], - "policyName": "string"
}
API path to update an existing custom category for the account. This API path will replace all the category information with the category details given in the request body.
categoryId required | integer ID of category to return |
Category details
name required | string |
description | string |
sites required | Array of strings <= 30000 items List of website urls and IP addresses |
comment | string Comment field appears in "Get Transaction Status" response, not in Cloud Web portal |
{- "name": "string",
- "description": "string",
- "sites": [
- "string"
], - "comment": "string"
}
{- "transactionId": "00000000-0000-0000-0000-000000000000",
- "status": "pending",
- "data": { },
- "comment": "string"
}
API path to add or remove sites from a custom category. This API path is only for adding or removing sites. To replace all the sites for a category the Update an existing category (PUT) API path must be used.
categoryId required | integer ID of category to return |
action required | string Enum: "add" "remove" Action identifying whether sites are being added or removed |
Site details
sites required | Array of strings <= 30000 items List of website urls and IP addresses |
comment | string Comment field appears in "Get Transaction Status" response, not in Cloud Web portal |
{- "sites": [
- "string"
], - "comment": "string"
}
{- "transactionId": "00000000-0000-0000-0000-000000000000",
- "status": "pending",
- "data": { },
- "comment": "string"
}
API path to delete a custom category for the account.
categoryId required | integer ID of category to return |
import requests def delete_category(url:str, headers: object) -> object: """Method to delete a Custom Category.""" response = requests.request("DELETE", url, headers=headers) print(response.text) return response token = "" # Insert bearer access token here category_id = 0 # Insert category id here host = "https://ws-custom-categories.api.forcepoint.io" api_version = "1.0.0" headers = {"Authorization": f"Bearer {token}"} url = f"{host}/v{api_version}/{category_id}" delete_category(url, headers)
{- "transactionId": "00000000-0000-0000-0000-000000000000",
- "status": "pending",
- "data": { },
- "comment": "string"
}
API path to retrieve the transaction status for a transaction ID.
transactionId required | string ID of transaction to return |
import requests def get_transaction_status(url: str, headers) -> object: """Get transaction status.""" response = requests.request( "GET", url, data="", headers=headers, ) print(response.text) return response token = "" # Insert bearer access token here transaction_id = "" # Insert transactionId here host = "https://ws-custom-categories.api.forcepoint.io" api_version = "1.0.0" url = f"{host}/v{api_version}/transaction/{transaction_id}" headers = {"Authorization": f"Bearer {token}"} get_transaction_status(url, headers)
{- "transactionId": "00000000-0000-0000-0000-000000000000",
- "status": "pending",
- "data": { },
- "comment": "string"
}