url_categories

The following methods allow for interaction with the ZIA URL Categories API endpoints.

Methods are accessible via zia.url_categories

Guidelines for adding / updating URLs

• The URL must use a standard URI format.

• The URL length cannot exceed 1024 characters.

• The URL cannot contain non-ASCII characters.

• The domain name before the colon (:) cannot exceed 255 characters.

• The domain name between periods (.) cannot exceed 63 characters.

Copyright (c) 2023, Zscaler Inc.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class URLCategoriesAPI

Bases: APIClient

A Client object for the URL Categories resources.

add_tld_category(configured_name, tlds, **kwargs)

Adds a new custom TLD category.

Parameters:

• name (str) – The name of the TLD category.

• tlds (list) – A list of TLDs in the format ‘.tld’.

• **kwargs – Optional keyword args.

Keyword Arguments:

description (str) – Description of the category.

Returns:

New TLD URL category resource record.

Return type:

Tuple

Examples

Create a tld category:

>>> added_category, _, error = client.zia.url_categories.add_tld_category(
...     configured_name=f"NewCategory_{random.randint(1000, 10000)}",
...     description="Google Finance",
...     tlds=['.co.uk'],
... )
... if error:
...     print(f"Error adding url category: {error}")
...     return
... print(f"url category added successfully: {added_category.as_dict()}")

add_url_category(super_category, urls=None, configured_name=None, **kwargs)

Adds a new custom URL category.

Parameters:

• configured_name (str) – Name of the URL category. This is only required for custom URL categories.

• super_category (str) – This field is required when creating custom URL categories.

• urls (list) – Custom URLs to add to a URL category.

• **kwargs – Optional keyword args.

Keyword Arguments:

• db_categorized_urls (list) – URLs entered will be covered by policies that reference the parent category, in addition to this one.

• description (str) – Description of the category.

• custom_category (bool) – Set to true for custom URL category. Up to 48 custom URL categories can be added per organisation.

• ip_ranges (list) – Custom IP addpress ranges associated to a URL category. This feature must be enabled on your tenancy.

• ip_ranges_retaining_parent_category (list) – The retaining parent custom IP addess ranges associated to a URL category.

• keywords (list) – Custom keywords associated to a URL category.

• keywords_retaining_parent_category (list) – Retained custom keywords from the parent URL category that are associated with a URL category.

• ip_ranges – Custom IP address ranges associated to a URL category. Up to 2000 custom IP address ranges can be added

• ip_ranges_retaining_parent_category – The retaining parent custom IP address ranges associated to a URL category. Up to 2000 custom IP address ranges can be added

Returns:

The newly configured custom URL category resource record.

Return type:

Tuple

Examples

Add a new category for beers that don’t taste good:

>>> added_category, _, error = client.zia.url_categories.add_url_category(
...     configured_name=f"NewCategory_{random.randint(1000, 10000)}",
...     super_category="BUSINESS_AND_ECONOMY",
...     description="Google Finance",
...     urls=['finance.google.com'],
...     keywords=["microsoft"],
...     custom_category=True,
...     db_categorized_urls=[".creditkarma.com", ".youku.com"]
... )
... if error:
...     print(f"Error adding url category: {error}")
...     return
... print(f"url category added successfully: {added_category.as_dict()}")

Add a new category with IP ranges:

>>> added_category, _, error = client.zia.url_categories.add_url_category(
...     configured_name=f"NewCategory_{random.randint(1000, 10000)}",
...     super_category="BUSINESS_AND_ECONOMY",
...     description="Google Finance",
...     urls=['finance.google.com'],
...     keywords=["microsoft"],
...     custom_category=True,
...     db_categorized_urls=[".creditkarma.com", ".youku.com"]
...     ip_ranges=['10.0.0.0/24']
... )
... if error:
...     print(f"Error adding url category: {error}")
...     return
... print(f"url category added successfully: {added_category.as_dict()}")

add_urls_to_category(category_id, **kwargs)

Adds URLS to a URL category.

Parameters:

• category_id (str) – The unique identifier of the URL category.

• urls (list) – Custom URLs to add to a URL category.

Returns:

The urls added to a category record.

Return type:

Tuple

Examples

>>> update_category, _, error = client.zia.url_categories.add_urls_to_category(
...     category_id='CUSTOM_01',
...     configured_name=f"NewCustomCategory{random.randint(1000, 10000)}",
...     urls=['finance1.google.com', 'finance2.google.com', 'finance3.google.com'],
... )
... if error:
...     print(f"Error updating url category: {error}")
...     return
... print(f"url category updated successfully: {update_category.as_dict()}")

delete_category(category_id)

Deletes the specified URL category.

Parameters:

category_id (str) – The unique identifier for the category.

Returns:

The status code for the operation.

Return type:

int

Examples

>>> _, _, err = client.zia.url_categories.delete_category(CUSTOM_01)
... if err:
...     print(f"Error deleting url category: {err}")
...     return
... print(f"url category with ID {CUSTOM_01} deleted successfully.")

delete_urls_from_category(category_id, **kwargs)

Deletes URLS from a URL category.

Parameters:

• category_id (str) – The unique identifier of the URL category.

• urls (list) – Custom URLs to delete from a URL category.

Returns:

The updated URL category resource record.

Return type:

Tuple

Examples

Remove the URL finance1.google.com from the list

>>> update_category, _, error = client.zia.url_categories.delete_urls_from_category(
...     category_id=added_category.id,
...     configured_name=added_category.configured_name,
...     urls=['finance2.google.com', 'finance3.google.com'],
... )
... if error:
...     print(f"Error updating url category: {error}")
...     return
... print(f"url category updated successfully: {update_category.as_dict()}")

get_category(category_id)

Returns URL category information for the provided category.

Parameters:

category_id (str) – The unique identifier for the category (e.g. ‘MUSIC’)

Returns:

The resource record for the url category.

Return type:

Tuple

Examples

>>> fetched_category, response, error = client.zia.url_categories.get_category('EDUCATION')
... if error:
...     print(f"Error fetching url category by ID: {error}")
...     return
... print(f"Fetched url category by ID: {fetched_category.as_dict()}")

get_quota()

Returns information on URL category quota usage.

Returns:

The URL quota statistics.

Return type:

Tuple

Examples

>>> quota = client.zia.url_categories.get_quota()
... print(quota)

list_categories(query_params=None)

Returns information on URL categories.

Parameters:

query_params (dict) –

Map of query parameters for the request.

[query_params.custom_only] {bool}: If set to true, gets information on custom URL categories only. [query_params.include_only_url_keyword_counts] {bool}: By default this parameter is set to false. [query_params.type] {str}: Filter by category type. Supported values: URL_CATEGORY, TLD_CATEGORY and ALL. [query_params.search] {str}: Local client-side search filter (not sent to API).

Returns:

A tuple containing (list of url categories instances, Response, error)

Return type:

tuple

Examples

>>> category_list, _, err = client.zia.url_categories.list_categories()
... if err:
...     print(f"Error listing url categories: {err}")
...     return
... print(f"Total url categories found: {len(category_list)}")
... for url in category_list:
...     print(url.as_dict())

Examples

>>> for categories in client.zia.url_categories.list_categories(query_params={'custom_only': True, }):
...     print(categories)

lookup(urls)

Lookup the category for the provided URLs.

Parameters:

urls (list) – The list of URLs to perform a category lookup on.

Returns:

A list of URL category reports.

Return type:

Tuple

Examples

>>> results, error = client.zia.url_categories.lookup(urls=["google.com, acme.com])
>>> if error:
...     print(f"Error during URL lookup: {error}")
...     return
... print("URL Lookup Results:")
... for entry in results:
...     print(entry)

review_domains_post(urls)

For the specified list of URLs, finds matching entries present in existing custom URL categories.

Parameters:

• urls (str) – The list of URLs that has a match in one or more existing custom URL categories

• domain_type – (str): The domain type of the URL. Supported Values: WILDCARD, SUBDOMAIN.

• matches (list) – Information about the list of categories where a URL match is found id: (str): The unique identifier assigned to the custom URL category name: (str): This attribute is populated with the name configured by the admin in the case of custom categories

Returns:

The url matches in one or more existing custom URL categories

Return type:

Tuple

Examples

>>> urls = ["acme.microsoft.com"]
... results = client.zia.url_categories.review_domains_post(urls)
... if not results:
...     print("No matches found in custom categories.")
...     return
... print("Matched results:")
... for item in results:
...     print(item)

review_domains_put(urls)

For the specified list of URLs, finds matching entries present in existing custom URL categories.

Parameters:

urls (str) – The list of URLs that has a match in one or more existing custom URL categories

Returns:

The url matches in one or more existing custom URL categories

Return type:

Tuple

Examples

>>> urls = ["acme.microsoft.com"]
... results = client.zia.url_categories.review_domains_put(urls)
... if not results:
...     print("No matches found in custom categories.")
...     return
... print("Matched results:")
... for item in results:
...     print(item)

update_url_category(category_id, action=None, **kwargs)

Updates a URL category.

This method supports two update modes with different behaviors:

1. Full Update (action=None): Replaces all URLs with the provided list

   • Any URLs not included in the request will be removed from the category

   • This is equivalent to completely replacing the URL list

   • Use this when you want to set the exact list of URLs for the category

2. Incremental Update (action specified): Adds or removes specific URLs while preserving existing ones

   • ADD_TO_LIST: Adds new URLs to the existing list (preserves all current URLs)

   • REMOVE_FROM_LIST: Removes specified URLs from the existing list (preserves other URLs)

   • Use this when you want to modify the existing URL list without affecting other URLs

Note: For incremental URL operations, you may also use the specialized functions:

• add_urls_to_category() - Convenience method for adding URLs (equivalent to action=”ADD_TO_LIST”)

• delete_urls_from_category() - Convenience method for removing URLs (equivalent to action=”REMOVE_FROM_LIST”)

Parameters:

• category_id (str) – The unique identifier of the URL category.

• action (str, optional) – The action to perform for incremental updates. - ADD_TO_LIST: Add URLs to the category (preserves existing URLs) - REMOVE_FROM_LIST: Remove URLs from the category (preserves existing URLs) - None: Perform full update (replaces all URLs with provided list)

• **kwargs – Optional keyword args.

Keyword Arguments:

• configured_name (str) – The name of the URL category.

• urls (list) – Custom URLs to add/remove/replace in the URL category. - For full updates: This list replaces all existing URLs - For incremental updates: This list is added to or removed from existing URLs

• db_categorized_urls (list) – URLs entered will be covered by policies that reference the parent category, in addition to this one.

• description (str) – Description of the category.

• ip_ranges (list) – Custom IP address ranges associated to a URL category. This feature must be enabled on your tenancy.

• ip_ranges_retaining_parent_category (list) – The retaining parent custom IP address ranges associated to a URL category.

• keywords (list) – Custom keywords associated to a URL category.

• keywords_retaining_parent_category (list) – Retained custom keywords from the parent URL category that are associated with a URL category.

Returns:

The updated url category resource record.

Return type:

Tuple

Examples

Full update - replace all URLs:

>>> update_category, _, error = client.zia.url_categories.update_url_category(
...     category_id="EDUCATION",
...     configured_name="Updated Education Category",
...     description="University websites",
...     urls=['.edu', 'harvard.edu', 'mit.edu'],
... )
>>> if error:
...     print(f"Error updating url category: {error}")
...     return
... print(f"url category updated successfully: {update_category.as_dict()}")

Incremental update - add URLs to existing list:

>>> update_category, _, error = client.zia.url_categories.update_url_category(
...     category_id="CUSTOM_01",
...     action="ADD_TO_LIST",
...     urls=['new-site1.com', 'new-site2.com'],
... )
>>> if error:
...     print(f"Error adding URLs to category: {error}")
...     return
... print(f"URLs added successfully: {update_category.as_dict()}")

Incremental update - remove URLs from existing list:

>>> update_category, _, error = client.zia.url_categories.update_url_category(
...     category_id="CUSTOM_01",
...     action="REMOVE_FROM_LIST",
...     urls=['old-site1.com', 'old-site2.com'],
... )
>>> if error:
...     print(f"Error removing URLs from category: {error}")
...     return
... print(f"URLs removed successfully: {update_category.as_dict()}")

Alternative using specialized functions:

Equivalent to action=”ADD_TO_LIST”

>>> update_category, _, error = client.zia.url_categories.add_urls_to_category(
...     category_id="CUSTOM_01",
...     urls=['new-site.com'],
... )

Equivalent to action=”REMOVE_FROM_LIST”

>>> update_category, _, error = client.zia.url_categories.delete_urls_from_category(
...     category_id="CUSTOM_01",
...     urls=['old-site.com'],
... )