Skip to content

Create Policy

POST/policies

DNS Protection API · Policies

Creates a new Policy and returns the newly created Policy. There is a limit of 50 Policies per account.

Required permissionswgaas.config:write

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.

Request body

Content type: application/json

Request body fields

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.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"My Policy\",
  \"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\"
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'My Policy',
    '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'},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "My Policy",
  "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"
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies" -Headers $headers -Body $body -ContentType "application/json"


package main

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

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies", strings.NewReader(`{
  "name": "My Policy",
  "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"
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    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: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "My Policy",
  "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"
}),
});
const data = await response.json();
console.log(data);

Responses

201 — Created.

Response fields

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.
409 Conflict.
500 Unexpected error.

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

Response examples

201

{
  "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.