List Policies¶

GET/policies

Returns all Policies.

Required permissionswgaas.config:read OR swgaas.config.dataplane:read

Parameters¶

Name	In	Type	Required	Description
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.
`page`	query	integer	No	The page number to fetch, starting with 1.
`pageSize`	query	integer	No	The size of the page requested.
`pageTotal`	query	boolean	No	Whether the number of pages should be calculated and returned in the response.
`name`	query	string	No	Filter request by name. Must match the pattern `^[a-zA-Z0-9\-_ ]+$`. Must be 1–100 characters long.
`nameContains`	query	string	No	Filter request where name contains the given value. Must match the pattern `^[a-zA-Z0-9\-_ ]+$`. Must be 1–100 characters long.
`categoryPolicy`	query	string	No	Filter policies by category policy, valid values are clean, optimal, bandwidth, business, blockAi, and custom (case insensitive). Must match the pattern `^([cC][lL][eE][aA][nN]\|[Oo][Pp][Tt][Ii][Mm][Aa][Ll]\|[Bb][Aa][Nn][Dd][Ww][Ii][Dd][Tt][Hh]\|[Bb][Uu][Ss][Ii][Nn][Ee][Ss][Ss]\|[Cc][Uu][Ss][Tt][Oo][Mm]\|[Bb][Ll][Oo][Cc][Kk][Aa][Ii])$`. Must be at least 1 character long.
`safeSearchYouTubeRestrictionLevel`	query	string	No	Filter policies by YouTube restriction level. Valid values are moderate and strict (case insensitive). Must match the pattern `^([Mm][Oo][Dd][Ee][Rr][Aa][Tt][Ee]\|[Ss][Tt][Rr][Ii][Cc][Tt])$`. Must be at least 1 character long.
`safeSearchForSearchEnginesEnabled`	query	boolean	No	Filter policies by safe search for search engines enabled status.
`safeSearchForYouTubeEnabled`	query	boolean	No	Filter policies by safe search for YouTube enabled status.
`sort`	query	array of string	No	List of one or more fields to sort by. Available fields to sort by are 'name', 'description', 'categoryPolicy', 'createdAt', and 'updatedAt'. Note that sorting is in alphabetical order. Examples: 'sort=name', 'sort=description:asc', 'sort=name,createdAt:desc'. Must contain 1–5 items. Each item must match the pattern `(^[^:]+$)\|(^[^:]+:(asc\|desc)$)`.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X GET "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"

import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies" -Headers $headers

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

const response = await fetch("https://api-<data-region>.central.sophos.com/dns-protection/v2/policies", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses¶

`200` — OK.¶

Response fields

pagesobject

Show child attributesHide child attributes

currentintegerrequired

The 1-based page number being returned.

sizeintegerrequired

The size of the page being returned.

totalinteger

(Optional) The total number of pages that exist, if pageTotal=true in the request.

itemsinteger

(Optional) The total number of items across all pages.

maxSizeintegerrequired

The maximum page size that can be requested.

itemsarray of object

List of policies.

Represents a Policy.

Show child attributesHide child attributes

idstring (uuid)required

The unique ID of this Policy.

namestringrequired

Name of the Policy.
Must match the pattern ^[a-zA-Z0-9\-_ ]+$. Must be 1–100 characters long.

descriptionstring

Description about the Policy.
Must be at most 250 characters long.

categoryPolicystring

Category of the Policy.
Must be one of: clean, optimal, bandwidth, business, custom, blockAi.

categoryGroupActionSettingsobject

Map of category group identifier to action (allow, block, alert, or custom). For example, productivity/allow, social/block, dataloss/allow.

rejectedWebCategoriesarray of integer

Rejected Web Categories of the Policy.
Must contain at most 500 items. Items must be unique. Each item must be ≥ 1 and ≤ 2147483647.

locationIdsarray of string (uuid)

The location ids assigned to this policy.
Items must be unique.

customDomainsEnabledboolean

Is allowed and blocked custom domains enabled.

allowedCustomDomainIdsarray of string (uuid)

The custom domain ids allowed by this policy.
Must contain at most 100 items. Items must be unique.

blockedCustomDomainIdsarray of string (uuid)

The custom domain ids blocked by this policy.
Must contain at most 100 items. Items must be unique.

safeSearchForSearchEnginesEnabledboolean

Is safesearch for search engine enabled.

safeSearchForYouTubeEnabledboolean

Is safesearch for youtube enabled.

safeSearchYouTubeRestrictionLevelstring

YouTube restriction level.
Must be one of: moderate, strict.

createdAtstring (date-time)required

The date/time when this Policy was created.

updatedAtstring (date-time)required

The date/time when this Policy was updated.

webcatVersioninteger

Webcat version of the policy.

Errors¶

Status	Meaning
`400`	Bad request.
`401`	Unauthorized.
`403`	Forbidden.
`500`	Unexpected error.

All error responses share the same shape — see the error response object.

Response examples¶

`200`¶

{
  "pages": {
    "current": 0,
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  },
  "items": [
    {
      "name": "My Policy",
      "id": "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
      "description": "Example Policy with comprehensive settings",
      "categoryPolicy": "optimal",
      "categoryGroupActionSettings": {
        "productivity": "allow",
        "social": "block",
        "dataloss": "block",
        "business": "allow",
        "bandwidth": "block",
        "infrastructure": "allow",
        "threats": "block",
        "uncategorized": "allow",
        "adult": "block"
      },
      "rejectedWebCategories": [
        1001,
        1002,
        1005
      ],
      "locationIds": [
        "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
        "e5f2aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3f"
      ],
      "customDomainsEnabled": true,
      "allowedCustomDomainIds": [
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      ],
      "blockedCustomDomainIds": [
        "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      ],
      "safeSearchForSearchEnginesEnabled": true,
      "safeSearchForYouTubeEnabled": true,
      "safeSearchYouTubeRestrictionLevel": "strict",
      "createdAt": "2025-01-01T12:00:00.686+00:00",
      "updatedAt": "2025-08-01T08:30:00.200+00:00",
      "webcatVersion": 1
    }
  ]
}

See the guide for a narrative walkthrough of this API.