Update Policy¶

PATCH/policies/{id}

Updates given Policy.

Required permissionswgaas.config:write

Parameters¶

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	A unique identifier of the Policy.
`X-Tenant-ID`	header	string (uuid)	Yes	Tenant ID.

Request body¶

Content type: application/json

Request body fields

namestring

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.

categoryPolicyOption 1 or Option 2

Category of the Policy.
As Option 1: must be one of: clean, optimal, bandwidth, business, custom, blockAi.

Option 1

Option 2

categoryGroupActionSettingsOption 1 or Option 2

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

Option 1

Option 2

rejectedWebCategoriesOption 1 or Option 2

Rejected Web Categories of the Policy. Send full array (replace), null (clear), or add/remove object (partial update).
As Option 1: must contain at most 500 items. As Option 1: items must be unique. As Option 1: each item must be ≥ 1 and ≤ 2147483647.

Option 1

Option 2

Partial update for a set of integers (e.g. rejected web category IDs). Use to add or remove items without sending the full list. - add: items to be added. Duplicates in the target set are ignored. - remove: items to be removed. Missing items in the target set are ignored.

Show child attributesHide child attributes

addarray of integer

Integers to add to the set.
Must contain at most 500 items. Items must be unique. Each item must be ≥ 1 and ≤ 2147483647.

removearray of integer

Integers to remove from the set.
Must contain at most 500 items. Items must be unique. Each item must be ≥ 1 and ≤ 2147483647.

locationIdsOption 1 or Option 2

The location ids assigned to this policy. Send full array (replace), null (clear), or add/remove object (partial update).
As Option 1: items must be unique.

Option 1

Option 2

Partial update for a set of UUIDs. Use to add or remove items without sending the full list. - add: items to be added. Duplicates in the target set are ignored. - remove: items to be removed. Missing items in the target set are ignored.

Show child attributesHide child attributes

addarray of string (uuid)

UUIDs to add to the set.
Must contain at most 100 items. Items must be unique.

removearray of string (uuid)

UUIDs to remove from the set.
Must contain at most 100 items. Items must be unique.

customDomainsEnabledboolean

Is allowed and blocked custom domains enabled.

allowedCustomDomainIdsOption 1 or Option 2

The custom domain ids allowed by this policy. Send full array (replace), null (clear), or add/remove object (partial update).
As Option 1: must contain at most 100 items. As Option 1: items must be unique.

Option 1

Option 2

Partial update for a set of UUIDs. Use to add or remove items without sending the full list. - add: items to be added. Duplicates in the target set are ignored. - remove: items to be removed. Missing items in the target set are ignored.

Show child attributesHide child attributes

addarray of string (uuid)

UUIDs to add to the set.
Must contain at most 100 items. Items must be unique.

removearray of string (uuid)

UUIDs to remove from the set.
Must contain at most 100 items. Items must be unique.

blockedCustomDomainIdsOption 1 or Option 2

The custom domain ids blocked by this policy. Send full array (replace), null (clear), or add/remove object (partial update).
As Option 1: must contain at most 100 items. As Option 1: items must be unique.

Option 1

Option 2

Partial update for a set of UUIDs. Use to add or remove items without sending the full list. - add: items to be added. Duplicates in the target set are ignored. - remove: items to be removed. Missing items in the target set are ignored.

Show child attributesHide child attributes

addarray of string (uuid)

UUIDs to add to the set.
Must contain at most 100 items. Items must be unique.

removearray of string (uuid)

UUIDs to remove from the set.
Must contain at most 100 items. Items must be unique.

safeSearchForSearchEnginesEnabledboolean

Is safesearch for search engine enabled.

safeSearchForYouTubeEnabledboolean

Is safesearch for youtube enabled.

safeSearchYouTubeRestrictionLevelOption 1 or Option 2

YouTube restriction level.
As Option 1: must be one of: moderate, strict.

Option 1

Option 2

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X PATCH "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies/<id>" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"My Policy\",
  \"description\": \"Example Policy\",
  \"locationIds\": {
    \"add\": [
      \"d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e\",
      \"e5f2aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3f\"
    ],
    \"remove\": [
      \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"
    ]
  }
}"

import requests

response = requests.patch(
    "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies/<id>",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'My Policy',
    'description': 'Example Policy',
    'locationIds': {   'add': [   'd4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e',
                                  'e5f2aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3f'],
                       'remove': ['a1b2c3d4-e5f6-7890-abcd-ef1234567890']}},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "My Policy",
  "description": "Example Policy",
  "locationIds": {
    "add": [
      "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
      "e5f2aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3f"
    ],
    "remove": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}'
Invoke-RestMethod -Method PATCH -Uri "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies/<id>" -Headers $headers -Body $body -ContentType "application/json"

package main

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

func main() {
    req, err := http.NewRequest("PATCH", "https://api-<data-region>.central.sophos.com/dns-protection/v2/policies/<id>", strings.NewReader(`{
  "name": "My Policy",
  "description": "Example Policy",
  "locationIds": {
    "add": [
      "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
      "e5f2aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3f"
    ],
    "remove": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}`))
    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/<id>", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "My Policy",
  "description": "Example Policy",
  "locationIds": {
    "add": [
      "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
      "e5f2aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3f"
    ],
    "remove": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
}),
});
const data = await response.json();
console.log(data);

Responses¶

`200` — OK.¶

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.
`404`	Not found.
`409`	Conflict.
`500`	Unexpected error.

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

Response examples¶

`200`¶

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

Update Policy¶

Parameters¶

Request body¶

Request samples¶

Responses¶

200 — OK.¶

Errors¶

Response examples¶

200¶

`200` — OK.¶

`200`¶