Skip to content

List Locations

GET/locations

DNS Protection API · Locations

Returns all Locations.

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.
type query string No Filter locations by type. Accepted values are "standard", "sfos", and "protectedBrowser" (case-insensitive).
Must match the pattern ^([sS][tT][aA][nN][dD][aA][rR][dD]|[sS][fF][oO][sS]|[pP][rR][oO][tT][eE][cC][tT][eE][dD][bB][rR][oO][wW][sS][eE][rR])$. Must be 1–16 characters long.
isDefault query string No Filter locations by default status (true or false).
Must match the pattern ^([tT][rR][uU][eE]|[fF][aA][lL][sS][eE])$. Must be 1–5 characters long.
ipAddressesContains query array of string No Filter locations by IPv4 and/or IPv6 addresses where the address contains the given value.
Must contain at most 100 items. Items must be unique.
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])?)*\.?)$.
includeDeleted query boolean No Filter locations by whether to include soft deleted locations or not.
sort query array of string No List of one or more fields to sort by. Available fields to sort by are 'name', 'description', and 'dohEnabled'. Note that sorting is in alphabetical order. Examples: 'sort=name', 'sort=description:asc', 'sort=name,description:desc'.
Must contain 1–3 items. Each item must match the pattern (^[^:]+$)|(^[^:]+:(asc|desc)$).

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/dns-protection/v2/locations" -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/locations",
    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/locations" -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/locations", 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/locations", {
  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 locations.
Represents a location.
Show child attributesHide child attributes
namestring
Location name.
Must match the pattern ^[a-zA-Z0-9\-_ ]+$. Must be 1–100 characters long.
idstring (uuid)
The unique ID of this location.
isDefaultboolean
Indicates if this is the default location.
descriptionstring
The description of this location.
Must be at most 250 characters long.
createdAtstring (date-time)
The date/time when this location was created.
updatedAtstring (date-time)
The date/time when this location was updated.
ipAddressesarray of string
The IPv4 and/or IPv6 list of addresses for this location. The combined number of items in ipAddresses and domainNames must not exceed 100.
Must contain at most 100 items. Items must be unique.
domainNamesarray of string
The list of domain names for this location. The combined number of items in ipAddresses and domainNames must not exceed 100.
Must contain at most 100 items. Items must be unique.
dohSecureLocationIdstring
The DNS Over HTTPS secure location ID, which is is a globally unique random ID generated for this location.
dohEnabledboolean
Indicates if the DNS Over HTTPS is enabled for this location.
policyIdstring (uuid)
The policy ID associated with this location.
dohUrlstring
typestring
Represents the type of a location.
Must be one of: standard, sfos, protectedBrowser.
labelstring
An optional label for this location.
Must be at most 256 characters long.
deletedAtstring (date-time)
The date/time when this location was soft deleted.
policyWebcatVersioninteger
Webcat version of the policy associated with this location.

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": "Headquarters",
      "id": "d4e1aee7-6c4e-4c9e-a8e2-1b1f4f7c4e3e",
      "isDefault": false,
      "description": "Main office location with secure DNS configuration.",
      "type": "standard",
      "label": "Main HQ",
      "createdAt": "2025-01-01T12:00:00.686+00:00",
      "updatedAt": "2025-08-01T08:30:00.200+00:00",
      "deletedAt": "2025-10-01T08:30:00.200+00:00",
      "ipAddresses": [
        "192.168.1.1",
        "192.168.1.2"
      ],
      "domainNames": [
        "hq.company.com",
        "internal.company.com"
      ],
      "dohSecureLocationId": "392oj0e54880r",
      "dohEnabled": true,
      "policyId": "e4f558e2-9f3a-44e0-a7a3-6b2f7b8b3d5d",
      "dohUrl": "https://392oj0e54880r.secure.dev.dnsprotection.sophos.com/dns-query",
      "policyWebcatVersion": 1
    }
  ]
}

See the guide for a narrative walkthrough of this API.