REST API overview All administration and configuration of SafeDNS Shield is performed through the REST API. The API listens on port 8080 of the same IP address that handles DNS queries. By default, access is restricted to a set of whitelisted IP addresses specified during deployment. Initial Configuration Example The following example demonstrates the initial configuration workflow. Send the following request: Type: POST 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       }   ],   "bw_lists": [      {           "profile_id": 1,           "type": "deny",           "domains": [               "example1.com",               "example2.com",               "example3.com"           ]       }   ],   "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": [] } The initialization query defines the full configuration applied to SafeDNS Shield. The following settings are processed in sequence: Filtering profile and block page – A filtering profile (ID=1) and a block page (ID=1) are 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: Type 0 – displays the blocked domain name. Type 1 – does not display the blocked domain name. Blacklist – Three domains are added to the blacklist for filtering profile 1. IP assignment – The profile is assigned one specific IP address and two subnets (/16 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. Once the request is sent and a successful response (HTTP status 204) is received, the initial configuration is complete. All subsequent DNS traffic processed by the server is handled according to the specified rules. Modifying Filtering Categories To modify the filtering categories for an existing profile, you must update the entire list of categories assigned to that profile. Adding new categories requires sending the full set (both current and new categories) in a single request. For example, the initial configuration created 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: PATCH URL: /profiles/1/ Data: { "cat_ids": [3, 4, 12, 66, 70, 71], "app_ids": [1, 12, 93], "profile": { "page_id": 1 } } In this request, the profile ID is specified directly in the URL. The request body contains the updated list of categories (original three and three new) while the AppBlocker categories and block page remain unchanged. Adding a Domain to the Allowlist 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: POST URL: /profile/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 the filtering profile. The following request adds domains in a batch operation for profile id=1: Type: POST URL: /profile/1/bw_list/batch Data: { "type": "deny", "domains": ["example5.com", "example6.com", "example7.com", "example8.com", "example9.com"] } Adding a Network or IP Address for Filtering To assign a new IP address or subnet to a filtering profile, send the following request. The example adds a single IP address by specifying a /32 network prefix for profile id=1: Type: POST 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, a /24 subnet would be specified as: {   "ip": "100.100.101.0",   "profile_id": 1,   "prefix_len": 24 } Removing an IP Address from Filtering To remove a previously assigned IP address or subnet from a filtering profile, send the following request: Type: DELETE URL: /net/1684300901 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: /net/1684301056 Data: { "ip": "100.100.101.0", "profile_id": 2, "prefix_len": 24 } To change the network prefix (for example, from /24 to /16), you must delete the existing record and add 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. 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 URL: /profiles/ Data: { "profile": { "id": 2, "page_id": 1 }, "cat_ids": [3, 4, 12, 66, 70, 71, 13], "app_ids": [1, 12, 93] } This creates profile id=2, configured with the same block page type and the same categories and AppBlocker settings as profile id=1, with the addition of the "Adult Related" category.