Web Security Cloud - API Documentation

API docs by Redocly

agw-euw2-wsc-p-custom-categories (1.0.0)

Download OpenAPI specification:

Public API for managing custom categories

Custom Category API

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 tokens. Clients must include a valid access token in the Authorization header of each request.

Example Header:
Authorization: Bearer YOUR_ACCESS_TOKEN

To obtain an access token, see the Token Management Public API.

Get all custom categories

API path to retrieve all custom categories for the account.

Authorizations:
custom-authorizer
query Parameters
cursor
string

Cursor for pagination

Responses

Request samples 

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 token here
next_page_cursor = "" # Insert next_page_cursor here (OPTIONAL)

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)

Response samples

Content type
application/json
{
  • "totalResults": 0,
  • "nextPageCursor": "string",
  • "categories": [
    ]
}

Create a new category

API path to create a new custom category for the account.

Authorizations:
custom-authorizer
Request Body schema: application/json
required
name
required
string
description
string
sites
Array of strings <= 30000 items

List of website URLs and IP addresses

policyName
string
comment
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "sites": [
    ],
  • "policyName": "string",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Get category and site counts and limits

API path to retrieve the number of sites, number of custom categories, site limits and custom category limits for the account.

Authorizations:
custom-authorizer

Responses

Response samples

Content type
application/json
{
  • "customCategoryCount": 1,
  • "customCategoryUrlCount": 1,
  • "customCategoryLimit": 1,
  • "customCategoryUrlLimit": 1
}

Get category by ID

API path to retrieve the details of a specific custom category by providing its ID.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

query Parameters
cursor
string

Cursor for pagination

Responses

Request samples 

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 token here
category_id = 0       # Insert category id here
next_page_cursor = "" # Insert next_page_cursor here (OPTIONAL)

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)

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "no name",
  • "description": "string",
  • "sites": [
    ],
  • "policyName": "string"
}

Update an existing category

API path to update an existing custom category for the account.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

Request Body schema: application/json
required

Category details

name
required
string
description
string
sites
required
Array of strings <= 30000 items

List of website urls and IP addresses

comment
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "sites": [
    ],
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Add or Remove category sites

API path to add or remove sites from a custom category.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

query Parameters
action
required
string
Enum: "add" "remove"

Action identifying whether sites are being added or removed

Request Body schema: application/json
required

Site details

sites
required
Array of strings <= 30000 items

List of website urls and IP addresses

comment
string

Responses

Request samples

Content type
application/json
{
  • "sites": [
    ],
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Delete a category

API path to delete a custom category for the account.

Authorizations:
custom-authorizer
path Parameters
categoryId
required
integer

ID of category to return

Responses

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Get transaction status

API path to retrieve the transaction status for a transaction ID.

Authorizations:
custom-authorizer
path Parameters
transactionId
required
string

ID of transaction to return

Responses

Request samples 

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 token here
transaction_id = "" # Insert transaction id 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)

Response samples

Content type
application/json
{
  • "transactionId": "00000000-0000-0000-0000-000000000000",
  • "status": "pending",
  • "data": { },
  • "comment": "string"
}

Token Management Public API

This API enables customers to generate an 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.

Generate a new token using api key

Generate a token that can be used for authorization purpose. To validate and verify the generated token, pass it to the platform's /oidc/introspect API.

header Parameters
X-API-KEY
required
string
Example: api-key-string

In this header you will have to pass your api key

Responses

Response samples

Content type
application/json
{
  • "token": "token-string"
}

command

Indicates that the operation is a command and modifies the state of the system

query

Indicates that the operation is a query and just queries the system with no state change