Skip to content

List Custom Domains

GET/custom-domains

DNS Protection API · Custom Domains List

Returns all Custom Domains.

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.
domainNames query array of string No Filter request by domain names where the domain name matches the given value.
Must contain at most 100 items. Each item must match the pattern ^([a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\.?)$.
sort query array of string No List of one or more fields to sort by. Available fields to sort by are 'name', 'description', 'createdAt', and 'updatedAt'. Note that sorting is in alphabetical order. Examples: 'sort=name', 'sort=description:asc', 'sort=name,createdAt:desc'.
Must contain 1–4 items. Each item must match the pattern (^[^:]+$)|(^[^:]+:(asc|desc)$).

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/dns-protection/v2/custom-domains" -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/custom-domains",
    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/custom-domains" -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/custom-domains", 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/custom-domains", {
  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 custom domain lists.
Represents a Custom Domain List.
Show child attributesHide child attributes
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.
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 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.