Update CDL by ID¶

PATCH/custom-domains/{id}

DNS Protection API · Custom Domains List

Updates given Custom Domains List.

Required permissionswgaas.config:write

Parameters¶

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

Request body¶

Content type: application/json

Request body fields

namestring

The name of this Custom Domain List.
Must match the pattern ^[a-zA-Z0-9\-_ ]+$. Must be 1–100 characters long.

descriptionstring

The description of this Custom Domain List.
Must be at most 250 characters long.

domainsOption 1 or Option 2

The Domains (or Websites) associated with this List.
As Option 1: must contain at most 1000 items. As Option 1: items must be unique. As Option 1: each item must be 1–255 characters long.

Option 1

Option 2

Extension of JSON patch for sets of strings. - add: items to be added. Ignore duplicate items in the target set. - remove: items to be removed. Ignore missing items in the target set.

Show child attributesHide child attributes

addarray of string

A set of string values.
Must contain at most 1000 items. Items must be unique. Each item must be 1–255 characters long.

removearray of string

A set of string values.
Must contain at most 1000 items. Items must be unique. Each item must be 1–255 characters long.

Request samples¶

cURLPythonPowerShellGoJavaScript

curl -X PATCH "https://api-<data-region>.central.sophos.com/dns-protection/v2/custom-domains/<id>" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"name\": \"My websites\",
  \"domains\": [
    \"example.com\",
    \"example.org\",
    \"example.net\"
  ]
}"

import requests

response = requests.patch(
    "https://api-<data-region>.central.sophos.com/dns-protection/v2/custom-domains/<id>",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'name': 'My websites',
    'domains': ['example.com', 'example.org', 'example.net']},
)
print(response.json())

$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "name": "My websites",
  "domains": [
    "example.com",
    "example.org",
    "example.net"
  ]
}'
Invoke-RestMethod -Method PATCH -Uri "https://api-<data-region>.central.sophos.com/dns-protection/v2/custom-domains/<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/custom-domains/<id>", strings.NewReader(`{
  "name": "My websites",
  "domains": [
    "example.com",
    "example.org",
    "example.net"
  ]
}`))
    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/custom-domains/<id>", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "My websites",
  "domains": [
    "example.com",
    "example.org",
    "example.net"
  ]
}),
});
const data = await response.json();
console.log(data);

Responses¶

`200` — OK.¶

Response fields

namestringrequired

The name of this Custom Domains List.
Must match the pattern ^[a-zA-Z0-9\-_ ]+$. Must be 1–100 characters long.

idstring (uuid)

The unique ID of this Custom Domains List.

descriptionstring

The description of this Custom Domains List.
Must be at most 250 characters long.

domainsarray of string

The Domains (or Websites) associated with this List.
Must contain at most 1000 items. Items must be unique. Each item must be 1–255 characters long.

createdAtstring (date-time)

The date/time when this custom domains list was created.

updatedAtstring (date-time)

The date/time when this custom domains list was updated.

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 websites",
  "id": "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
  "description": "Example Custom Domain List for a series of owned FQDN",
  "domains": [
    "example.com",
    "example.org",
    "example.net"
  ],
  "createdAt": "2025-01-01T12:00:00.686+00:00",
  "updatedAt": "2025-08-01T08:30:00.200+00:00"
}

See the guide for a narrative walkthrough of this API.