REST API overview

All administration and configuration of SafeDNS Shield filtering configuration is performedmanaged through theits REST API. The API listensaddress onis deployment-specific. The default management API port is 8080, but the host, protocol, and port may be changed during deployment.

Use the following placeholder throughout this guide:

<base-url> = http[s]://<shield-management-host>:<management-api-port>

For example:

http://192.0.2.10:8080

Access is normally restricted to source addresses approved during deployment.

Using the API

Authentication

All client-facing API requests require an HTTP bearer token.

Authorization: Bearer <token>
Content-Type: application/json

Example:

curl \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  "<base-url>/profiles/"

Use the token and management API address assigned to the Shield deployment.

General behavior

Successfully completed configuration changes take effect immediately. No service restart or separate activation request is required. Successful create operations normally return 201 Created. Successful update and retrieval operations normally return 200 OK. Successful deletion and initialization operations return 204 No Content with no response body. Invalid request data may return 422 Unprocessable Entity with validation details. IPv4 addresses are supplied as dotted-decimal strings in request bodies, but some resource paths identify an IPv4 address by its unsigned integer representation. The examples use trailing slashes where they appear in the API specification.

Profiles and filtering

A filtering profile combines category rules, application rules, block-page behavior, and several profile-level options.

Profile fields

Field Type Description id integer Client-supplied profile identifier. Required when creating a profile. page_id integer or null Identifier of the sameblock IPpage addressassigned thatto handlesthe profile. white_list_only boolean When enabled, only domains on the allowlist and explicitly allowed applications are permitted. Default: false. empty_dns_answer boolean When enabled, Shield returns an empty DNS queries.answer Byfor default,a accessblocked isdomain restrictedinstead of directing the client to a setblock page. Default: false. appaware_priority_over_bwlists boolean When enabled, application rules take priority over explicit domain allow/deny-list rules. Default: false.

A profile request also supports:

Field Type Description cat_ids array of whitelistedintegers IPComplete addressescollection specifiedof duringfiltering deployment.category IDs assigned to the profile. apps array of objects Complete collection of application rules assigned to the profile.

Each application rule contains:

{
  "app_id": 12,
  "status": "deny"
}

Supported statuses are:

deny — blocks domains associated with the application. allow — explicitly permits resolution of domains associated with the application, including when those domains would otherwise be blocked by the profile's category rules.

Application IDs can be obtained from:

GET /app_aware/application/

Category IDs are listed in the SafeDNS category reference.

Replacement semantics

When cat_ids or apps is included in:

PATCH /profiles/{profile_id}

it replaces the complete existing collection. It is not merged with the current configuration.

Omitting cat_ids leaves the category collection unchanged. Sending "cat_ids": [] removes all category assignments. Omitting apps leaves the application-rule collection unchanged. Sending "apps": [] removes all application rules.

Initial Configurationconfiguration Example

example

The following/init/ exampleoperation demonstratescreates the initial Shield configuration workflow.in Sendone the following request:request.

• Type: Method: POST

• URL: <domainbase-url>/init/
  
• Data:

{
    "profiles": [
        {
            "profile": {
                "id": 1,
                "page_id": 1
            },
            "cat_ids": [3, 4, 12],
            "app_ids": [1, 12, 93]
        }
    ],
  "blockpages": [
    {
      "id": 1,
      "type": 0
    },
    {
      "id": 2,
      "type": 1
    }
  ],
  "profiles": [
    {
      "profile": {
        "id": 1,
        "page_id": 1,
        "white_list_only": false,
        "empty_dns_answer": false,
        "appaware_priority_over_bwlists": false
      },
      "cat_ids": [3, 4, 12],
      "apps": [
        {
          "app_id": 1,
          "status": "deny"
        },
        {
          "app_id": 12,
          "status": "deny"
        },
        {
          "app_id": 93,
          "status": "deny"
        }
      ]
    }
  ],
  "bw_lists": [
    {
      "profile_id": 1,
      "type": "deny",
      "domains": [
        "example1.com",
        "example2.com",
        "example3.com"
      ]
    }
  ],
  "napts": [],
  "nets": [
    {
      "ip": "100.100.100.100",
      "profile_id": 1,
      "prefix_len": 32
    },
    {
      "ip": "100.110.110.0",
      "profile_id": 1,
      "prefix_len": 24
    },
    {
      "ip": "100.120.0.0",
      "profile_id": 1,
      "prefix_len": 16
    }
  ],
  "nets6": [],
    "napts": []
}

TheAll initializationsix querytop-level defines the full configuration applied to SafeDNS Shield. The following settingsarrays are processedrequired. inInclude sequence:

an

empty array

Filtering profile and block page – A filtering profile (ID=1) andwhen a blockresource pagetype (ID=1)is arenot created.

Blocked categories – Three DNS categories are blocked for the profile: malware, phishing, and botnets.

Blocked applications – Three AppBlocker categories are blocked: Slack, AnyDesk, and Netflix.

Block pages – Two block pages of different types are created:used:

• Type 0 – displays the blocked domain name.

  blockpages
• profiles

bw_lists napts nets nets6

The example creates:

Two block-page records:

Type 0: default block page. Type 1: –custom doesblock not display the blocked domain name. page. Profile

Blacklist1, – Three domains are addedassigned to theblock blacklistpage for filtering profile 1.

1. Three

IPblocked content/security categories.

Three denied applications. Three explicitly denied domains. One IPv4 host assignment – The profile is assigned one specific IP address and two subnetsIPv4 (/16subnet and /24). DNS requests from these sources are filtered according to the profile’s policy.

IPv6 and NAT‑port identification – The nets6 (IPv6) and napts (NAT port‑based identification) sections are included but left empty. These fields must be present in the request even if not used, to trigger the creation of the initial configuration.

assignments.

OnceCustom block-page content is configured outside the requestShield isREST sentAPI. The API only creates and aassigns the block-page record.

A successful responseinitialization (HTTPreturns:

status 

204 No Content
)

is received, the initial

Profile configuration is complete. All subsequent DNS traffic processed by the server is handled according to the specified rules.

Modifying Filtering Categories

examples

To modify theModifying filtering categories

for

To an existing profile, you must update the entire list ofchange categories assigned to thata profile.profile, Addingsend newthe complete desired category collection.

The following request replaces the existing categories requires sending the full set (both current and new categories) in a single request.

For example, the initial configuration createdof profile id=1 with three blocked categories: malware, phishing, and botnets. To add Cryptojacking, DGA, and Ransomware, the request must include all six categories:

• Type: Method: PATCH

• URL: <domainbase-url>/profiles/1/
  
• Data:

{
  "cat_ids": [3, 4, 12, 66, 70, 71]
}

Because apps and profile are omitted, only the category collection is changed.

To remove all category assignments:

{
  "cat_ids": []
}

Replacing application rules for a profile

Application rules can be replaced together through the profile endpoint.

Method: PATCH URL: <base-url>/profiles/1

{
  "apps": [
    {
      "app_id": 1,
      "status": "deny"
    },
    {
      "app_id": 12,
      "status": "allow"
    }
  ]
}

This request removes any other application rules previously assigned to profile 1. It denies application 1 and explicitly permits domains associated with application 12, even if category rules would otherwise block them.

To remove all application rules:

{
  "apps": []
}

Managing individual application rules

Retrieve the application catalogue

Method: GET URL: <base-url>/app_aware/application/

Example response:

[
  {
    "id": 1,
    "name": "Application name"
  }
]

Retrieve all application rules for a profile

Method: GET URL: <base-url>/profile/1/app_aware

Example response:

[
  {
    "profile_id": 1,
    "app_id": 12,
    "status": "allow"
  }
]

Add one application rule

Method: POST URL: <base-url>/profile/1/app_aware

{
  "app_id": 12,
  "status": "allow"
}

Add several application rules with the same status

Method: POST URL: <base-url>/profile/1/app_aware/batch

{
  "app_ids": [1, 12, 93],
  "profile"status": {
    "page_id": 1deny"
}
}

InDelete thisan request,application rule

The final path value is the profileapplication IDID. The current OpenAPI parameter name is specifiedapp_aware_id, directlybut init identifies the URL.same Thevalue as app_id.

Method: DELETE URL: <base-url>/profile/1/app_aware/12

No request body containsis the updated list of categories (original three and three new) while the AppBlocker categories and block page remain unchanged.required.

Adding a Domaindomain to the Allowlistallowlist

To exempt a specific domain from category-based blocking, add it to the allowlist of the relevant filtering profile. For profile id=1, send the following request:

• Type: Method: POST

• URL: <domainbase-url>/profile/1/1/bw_list
  
• Data:
  

{
  "type": "allow",
  "domain": "example4.com"
}

This adds the domain to the allowlist, giving it priority over category-based blocking.

Adding Domains to the Denylist

To block specific domains that are not covered by the configured categories, add them directly to the denylist

for

To block several domains directly, use the filtering profile. The following request adds domains in a batch operation for profile id=1:operation.

• Type: Method: POST
• URL: <domainbase-url>/profile/1/1/bw_list/batch
• Data:

{
  "type": "deny",
  "domains": [
    "example5.com",
    "example6.com",
    "example7.com",
    "example8.com",
    "example9.com"
  ]
}

Adding

Allow/deny-list astorage Networklimitation

Shield stores allowlist and denylist domains as hashes. The API therefore cannot retrieve or IPenumerate Addressthe fororiginal Filtering

domain names after they have been submitted.

ToAPI assignclients should retain their own copy of configured allowlists and denylists when later inspection, reconciliation, or synchronization is required.

Update and delete operations still accept the original domain name. Shield calculates its hash internally to locate the stored rule.

Creating a new IPfiltering profile

Method: POST URL: <base-url>/profiles/

{
  "profile": {
    "id": 2,
    "page_id": 1,
    "white_list_only": false,
    "empty_dns_answer": false,
    "appaware_priority_over_bwlists": false
  },
  "cat_ids": [3, 4, 12, 13, 66, 70, 71],
  "apps": [
    {
      "app_id": 1,
      "status": "deny"
    },
    {
      "app_id": 12,
      "status": "deny"
    },
    {
      "app_id": 93,
      "status": "deny"
    }
  ]
}

This creates profile 2, assigns block page 1, enables the listed filtering categories, and adds three denied application rules.

Subscriber assignments

Assigning an IPv4 address or subnet

To assign an IPv4 host to aprofile filtering1, profile, send the following request. The example addscreate a single IP address by specifying a /32 network prefix for profile id=1:record.

• Type: Method: POST
• URL: <domainbase-url>/net/
• Data:

{
  "ip": "100.100.100.101",
  "profile_id": 1,
  "prefix_len": 32
}

To add an entire subnet, adjust the prefix length accordingly. For instance,assign a /24 subnet would be specified as:subnet:

{
  "ip": "100.100.101.0",
  "profile_id": 1,
  "prefix_len": 24
}

Removing

Supported IPv4 prefix lengths are /10 through /32.

Retrieve all IPv4 assignments

Method: GET URL: <base-url>/net/

Example response:

[
  {
    "ip": "100.100.100.101",
    "profile_id": 1,
    "prefix_len": 32
  },
  {
    "ip": "100.100.101.0",
    "profile_id": 1,
    "prefix_len": 24
  }
]

IPv4 integer representation

Individual IPv4 resource paths identify an IPaddress Addressby its unsigned 32-bit integer representation.

For example:

100.100.100.101 = 1684300901
100.100.101.0   = 1684301056

Python conversion example:

from Filtering

ipaddress import IPv4Address int_ip = int(IPv4Address("100.100.100.101")) print(int_ip) # 1684300901

ToReassign removean a previously assigned IPIPv4 address or subnet from a filtering profile, send the following request:

• Type: DELETE
  Method: PATCH
• URL: <domainbase-url>/net/16843009011684301056
  
• Data: None

This request has no body. The IP address must be provided in decimal format in the URL. Use the exact address originally submitted, without the mask - for example, 100.100.100.101 or 100.100.101.0 from the earlier examples. You can convert an IP address to decimal format using a tool like this one.

Modifying the Filtering Profile for a Specific IP

To change the filtering profile assigned to an existing IP address or subnet, send the following request. The IP address must be provided in decimal format in the URL. This example reassigns the address 100.100.101.0 (originally a /24 subnet) from profile id=1 to profile id=2:

Type: PATCH URL: <domain>/net/1684301056 Data:

{
  "ip": "100.100.101.0",
  "profile_id": 2,
  "prefix_len": 24
}

Remove an IPv4 address or subnet

Method: DELETE URL: <base-url>/net/1684301056

No request body is required.

Assigning an IPv6 address or subnet

Method: POST URL: <base-url>/net6/

{
  "ip": "2001:db8:100::",
  "profile_id": 1,
  "prefix_len": 64
}

Supported IPv6 prefix lengths are /16 through /128.

Retrieve all IPv6 assignments

Method: GET URL: <base-url>/net6/

Example response:

[
  {
    "ip": "2001:db8:100::",
    "profile_id": 1,
    "prefix_len": 64
  }
]

Identifying subscribers through NAPT port ranges

NAPT records assign different source-port ranges on a shared IPv4 address to different filtering profiles.

Port boundaries are inclusive. A range from 10000 to 19999 includes both port 10000 and port 19999.

Create a NAPT assignment

Method: POST URL: <base-url>/napt/

{
  "ip": "203.0.113.10",
  "lower_port_bound": 10000,
  "upper_port_bound": 19999,
  "profile_id": 1
}

Port values must be between 0 and 65535. The complete port range is 0 through 65535.

Create several NAPT assignments

Method: POST URL: <base-url>/napt/batch

[
  {
    "ip": "203.0.113.10",
    "lower_port_bound": 10000,
    "upper_port_bound": 19999,
    "profile_id": 1
  },
  {
    "ip": "203.0.113.10",
    "lower_port_bound": 20000,
    "upper_port_bound": 29999,
    "profile_id": 2
  }
]

Retrieve all NAPT assignments for an IPv4 address

The path uses the integer representation of the IPv4 address.

Method: GET URL: <base-url>/napt/3405803786

3405803786 is the integer representation of 203.0.113.10.

Delete several NAPT assignments

Unlike individual NAPT resource paths, the batch-deletion body uses dotted-decimal IPv4 strings.

Method: DELETE URL: <base-url>/napt/batch

[
  {
    "ip": "203.0.113.10",
    "lower_port_bound": 10000,
    "upper_port_bound": 19999
  },
  {
    "ip": "203.0.113.10",
    "lower_port_bound": 20000,
    "upper_port_bound": 29999
  }
]

profile_id is not included in the batch-deletion request.

Profile schedules

A schedule temporarily switches one profile to another during specified periods.

The profile identified in the URL is the source profile. target_profile_id identifies the profile used during scheduled periods. A profile cannot target itself.

Supported day formats

Both weekday names and integers are accepted:

Integer Weekday 0 Monday 1 Tuesday 2 Wednesday 3 Thursday 4 Friday 5 Saturday 6 Sunday

Weekday names must be lowercase:

monday, tuesday, wednesday, thursday, friday, saturday, sunday

Examples in this guide use weekday names for readability.

Times use HH:MM format and must fall on 30-minute boundaries, such as 08:00, 12:30, or 18:00. 00:00 represents the start of a day and 24:00 represents the end of a day.

Create a schedule

Method: POST URL: <base-url>/profile/1/schedule

{
  "target_profile_id": 2,
  "periods": [
    {
      "start": {
        "day": "monday",
        "time": "18:00"
      },
      "end": {
        "day": "tuesday",
        "time": "08:00"
      }
    },
    {
      "start": {
        "day": 5,
        "time": "00:00"
      },
      "end": {
        "day": 5,
        "time": "24:00"
      }
    }
  ]
}

This example switches profile 1 to profile 2 from Monday evening through Tuesday morning and for the whole of Saturday.

Update a schedule

Method: PATCH URL: <base-url>/profile/1/schedule

To change the networktarget prefixprofile (for example,all fromexisting periods:

/24{
  "target_profile_id": 3
}

to

To replace all existing periods:

/16){
  "periods": [
    {
      "start": {
        "day": "friday",
        you"time": must"18:00"
      delete},
      "end": {
        "day": "monday",
        "time": "08:00"
      }
    }
  ]
}

When periods is supplied, all previously configured periods are deleted and replaced by the existingsubmitted recordcollection.

and add

Delete a new one with the correct network address. In this case, you would delete 100.100.101.0 and add 100.100.0.0 with the /16 prefix.schedule

Creating a New Filtering Profile

Before an IP can be reassigned to a different profile, that profile must exist. The following request creates a new filtering profile:

• Type: POST
  Method: DELETE
• URL: <domainbase-url>/profiles/profile/1/schedule
  

No request body is required.

Block pages

Block-page records use two types:

Type Meaning 0 Default block page 1 Custom block page

Example creation request:

Method: POST Data: URL: <base-url>/blockpage/

{
    "profile": {
  "id": 2,
  "page_id"type": 1
},
"cat_ids": [3, 4, 12, 66, 70, 71, 13],
    "app_ids": [1, 12, 93]
}

ThisCustom createsblock-page profilecontent id=2,is configured withoutside the sameShield blockREST pageAPI.

type

Further reference

For a complete list of methods, request models, response models, and thevalidation sameconstraints, categories and AppBlocker settings as profile id=1, withsee the additionSafeDNS ofShield theREST "AdultAPI Related" category.reference.