Getting started

What you will build¶

This guide explains how to create and manage Web Filtering Profiles and Site Lists. After reading it, you can:

• Retrieve the available website categories.
• Create a Web Filtering Profile with per-category allow, warn, or block rules.
• Create Site Lists to manage specific sites.
• Apply a Profile to a Sophos product.

What is a Web Filtering Profile?

A Web Filtering Profile defines how website categories are handled for users on protected devices. Each category can use allow, warn, or block. With warn, users see a warning page but can proceed.

Profiles can also reference Site Lists. These let you allow, warn, or block specific sites regardless of their category.

Profiles are designed to be created once and reused across multiple policies and products. This helps you keep web filtering rules consistent. Change the Profile once, and policies that reference it use the updated rules automatically.

Web Filtering Profiles currently support Sophos Endpoint and Server. Support for additional Sophos products will be added in future releases.

This guide follows one path from a category preset to an applied policy:

1. Get the available presets and categories.
2. Create a profile and, if needed, add a site list.
3. Apply the profile to an Endpoint or Server Web Control policy.

A policy connects the Profile to the devices it covers.

Prerequisites¶

You must have a set of API credentials (service principal) to call the Web Filtering API. For more information, refer to the appropriate quick start guide:

• Sophos partners: Read the Partner Getting Started guide first.
• Enterprise customers: If you use Sophos Enterprise to manage multiple tenants, read the Organization Getting Started guide first.
• Other customers: Read the Tenant Getting Started guide first.

Get credentials¶

Use the getting started guide for your account type to create a service principal and get its client ID and secret. Follow its authentication steps to get a JWT access token. Use that token and your tenant ID in the requests below.

First authenticated call¶

You can use any HTTP client, such as cURL or Postman. The first request uses cURL. Later requests show the method, path, and JSON body separately.

The Web Filtering API and Endpoint API share a regional host. Their paths start with /web-filters/v1 and /endpoint/v1, respectively.

Get the available presets and categories before you create a Profile. Replace the placeholders with your access token, tenant ID, and data region.

curl --request GET \
  --url "https://api-<data-region>.central.sophos.com/web-filters/v1/profiles/metadata" \
  --header "Authorization: Bearer <jwt>" \
  --header "X-Tenant-ID: <tenant-id>"

The response contains a presets array and a categories array. Use their names in later requests. This shortened example shows the fields you need; your tenant's names can differ.

{
  "presets": [{ "name": "<preset-name>" }],
  "categories": [{ "name": "<category-name>", "group": "<group-name>" }]
}

The following requests use the short method and path form. Send the same authorization and tenant headers with each request. For requests with a JSON body, also send Content-Type: application/json.

Create a profile¶

To create a Profile, send a name, an optional description, and its category configuration. Set filterByCategory to true to use category rules.

You can set category actions in three ways:

• preset: Use a preset name from the metadata response.
• categoryGroupActions: Set one action for each category group you choose.
• categoryActions: Set allow, warn, or block for individual categories.

You can combine group and category actions. Every category must have exactly one action assigned to it.

The create Profile operation shows their full request schemas.

The following example uses a preset, which defines the category actions without listing each category:

POST /web-filters/v1/profiles

Request body:

{
  "name": "Standard Web Policy",
  "description": "Uses a category preset.",
  "filterByCategory": true,
  "preset": "<preset-name>"
}

The API returns 201 Created. Save the id from the response as your <profile-id>.

To set a per-category rule instead, omit preset and use names from the metadata response. This example shows the shape for one category; add the other categories you need.

{
  "name": "Example category profile",
  "filterByCategory": true,
  "categoryActions": [
    { "name": "<category-name>", "action": "block" }
  ]
}

Add a site list (optional)¶

Site Lists let you manage specific sites independently of category rules. Entries in a Site List override category behaviour. For example, you can explicitly block a site even if its category is set to allow, or allow a site whose category is blocked.

You can reuse the same Site List across multiple Profiles. Each list can contain up to 750 sites, and a tenant can have up to 20 lists.

Create a Site List when you need a rule for specific sites. The API returns its id as your <site-list-id>.

POST /web-filters/v1/site-lists

Request body:

{
  "name": "Blocked Social Media Sites",
  "description": "Specific sites blocked regardless of category.",
  "sites": ["tiktok.com", "reddit.com"]
}

Add the site list to the profile. Send the profile's full definition so that the update keeps its existing category settings. Use the preset name from your metadata response and the site list ID returned above.

PUT /web-filters/v1/profiles/{profileId}

Request body:

{
  "name": "Standard Web Policy",
  "filterByCategory": true,
  "preset": "<preset-name>",
  "filterBySiteList": true,
  "siteListActions": [
    {
      "id": "<site-list-id>",
      "action": "block",
      "priority": 1
    }
  ]
}

If you add more site lists, give each a unique priority. A higher number takes priority over a lower one. See update profile for the full request schema.

Apply the profile to a policy¶

Apply a Web Filtering Profile through the API of the Sophos product that uses it. For Endpoint and Server devices, update a Web Control policy through the Endpoint API. Devices assigned to that policy then use the Profile's rules.

Find the Web Control policy you want to update. Use web-control for Endpoint policies or server-web-control for Server policies. Save its id as your <policy-id>.

GET /endpoint/v1/policies?policyType=web-control

This request uses https://api-<data-region>.central.sophos.com with the Endpoint path shown above. The get policies operation explains pagination if your tenant has many policies.

Set all three Web Control settings together:

• endpoint.web-control.filter-by-web-profile.enabled turns on filtering by Profile.
• endpoint.web-control.web-profile.enabled selects Profile settings instead of classic Web Control settings.
• endpoint.web-control.web-profile-id identifies the Profile to apply.

Replace <profile-id> with the ID returned when you created the Profile.

PATCH /endpoint/v1/policies/{policyId}/settings

Request body:

{
  "endpoint.web-control.web-profile.enabled": { "value": true },
  "endpoint.web-control.filter-by-web-profile.enabled": { "value": true },
  "endpoint.web-control.web-profile-id": { "value": "<profile-id>" }
}

Each setting must be an object with a value field. See update policy settings and the Web Control settings for details.

You can assign the same Profile to multiple policies. This keeps the category rules and Site Lists consistent across those policies.

Devices that do not support Web Filtering Profiles fall back to the next applicable policy.

Verify it worked¶

Get the profile and check its id, preset, and, if you added a site list, siteListActions.

GET /web-filters/v1/profiles/{profileId}

Get the policy settings and check the three endpoint.web-control values from the PATCH request.

GET /endpoint/v1/policies/{policyId}/settings

If a call fails, check the tenant ID, data region, token, and required permission. The error guide explains API error responses.

What to do next¶

• Use the Web Filtering API overview to explore profile and site list operations.
• Read the Endpoint API overview for more policy operations.
• Review pagination when listing many profiles or policies.

The entries below cover the other Profile and Site List operations.

Manage profiles and site lists¶

Add, replace, or remove sites¶

After you create a Site List, you can add one site at a time. Save the new site's id if you need to remove it later.

POST /web-filters/v1/site-lists/{siteListId}/sites

Request body:

{
  "site": "example.com"
}

To replace all entries, send the complete sites array to the update Site List operation. The PUT request replaces the list; it does not append to it.

PUT /web-filters/v1/site-lists/{siteListId}

Request body:

{
  "name": "Blocked Social Media Sites",
  "description": "Specific sites blocked regardless of category.",
  "sites": ["tiktok.com", "reddit.com", "example.com"]
}

You can also list a Site List's entries or remove one by its siteId:

GET /web-filters/v1/site-lists/{siteListId}/sites

DELETE /web-filters/v1/site-lists/{siteListId}/sites/{siteId}

Clone a Profile¶

To copy an existing Profile, for example to create a variant for a different team with slightly different rules:

POST /web-filters/v1/profiles/{profileId}/clone

Request body:

{
  "name": "Standard Web Policy - Finance Team"
}

List Profiles¶

List Profiles for the tenant, or retrieve one by its ID:

GET /web-filters/v1/profiles

GET /web-filters/v1/profiles/{profileId}

Delete Profile¶

Delete a Profile only after removing it from every policy that uses it:

DELETE /web-filters/v1/profiles/{profileId}

For complete request and response schemas, see the Web Filtering API reference.