JSON-RPC API guide Version 1.1.The latest JSON-RPC API guide is available here: https://docs.safedns.com/books/json-rpc-api/page/json-rpc-api-guide JSON-RPC API methods are designed for interaction with the service and making changes to the settings. The API was designed using JSON-RPC protocol and is compatible with the following versions: 1.0 and 2.0. More info is available here: http://www.jsonrpc.org/specification An example of a CURL request for JSON-RPC 1.0: curl -X POST https://www.safedns.com/api/json/v1-L-d '{"id":0,"method":"methodName","params":{"param1":"param1"}}' An example of a CURL request for JSON-RPC 2.0: curl -X POST https://www.safedns.com/api/json/v2-L-d '{"id":0,"jsonrpc":"2.0","method":"methodName","params":{"param1":"para m1"}}' Some API methods require basic authentication. In this case, authentication details must be sent in the request. Example: curl -X POST https://www.safedns.com/api/json/v2 -L --user username:password -d '{"id":0,"jsonrpc":"2.0","method":"methodName","params":{"param1":"param1"}}' Response format: JSON. A response example of a successful API call: { "jsonrpc": "2.0", "id": 0, "result": "result" } A method result is included in the “result” key. In case of an incorrect request the response will be the following: { "jsonrpc": "2.0", "id": 0, "error": {"code": "code", "name": "name", "message": "message", "data": "data"} } Table of available methods: # Value Description 1 systemInfo Gets information about the system configuration 2 myip Gets the current client’s IP 3 testAuth User’s authentication 4 register Registers a new user 5 userInfo Gets user information 6 profiles Gets a list of available filtering policies 7 addProfile Creates a new filtering policy 8 removeProfile Deletes a filtering policy 9 renameProfile Renames a filtering policy 10 categories Gets a list of available filtering categories 11 userFilter Gets a list of filtering categories applied for a user 12 setFilterCat Changes filtering settings 13 domains Gets a list of Allow/Denylisted domains for a certain filtering policy 14 addDomain Adds a domain to the Allow/Denylist for a certain filtering policy 15 removeDomain Deletes a domain from a certain filtering policy 16 clearDomains Clears the list of domains for a certain filtering policy 17 updateNic Updates a dynamic IP 18 setWhiteListOnly Enables/disables the "Allow list only" mode 19 setSafeSearchEnabled Enables/disables "Safe Search mode" for Google and Bing 20 setSafeYoutubeEnabled Enables/disables "Restricted YouTube mode" 21 multiSchedule Gets information on the filtering schedule for a certain policy 22 setSchedule Sets filtering schedule for a certain policy 23 setScheduleEnabled Enables/disables filtering schedule for a certain policy 24 profileScheduleActivity Gets the time left before a change of the filtering policy according to the filtering schedule 25 getProfile Creates AgentInfo, gets AgentInfo status or updates AgentInfo policy depending on the parameters 26 setProfile Sets a filtering policy for AgentInfo 27 feedback Sends user’s feedback 28 getCategoriesDailyStats Gets daily categories stats of a policy 29 getAdvertising Gets the information on promo 30 getPlans Gets the list of available billing plans 31 getPlan Gets the user’s billing plan 32 getAPCVersion Gets mobile app’s version: minimal supported and the current one Available methods: 1. systemInfo Gets information on the system settings. Response: { "public_dns": , "nxdomain": , "blockpage": , "blockpage_token": , "blockapi": } 2. myip Gets current client’s IP. Response: 3. testAuth User’s authentication. Mandatory parameters: username - client’s username. password - client’s password. Response: 4. register‌ Registers a new user. Mandatory parameters: username - client’s username. password - client's password. Response: In case of a successful registration: [true] If an error occurred: [false, ] 5. userInfo Gets user information. Authorization is required. Response: { "plan": { "name": , "code": , "features": }, "tz": , "tz_minutes": } 6. profiles Gets a list of available filtering policies. Authorization is required. Response: [ { "name": , "default": , "white_list_only":, "token": , "safe_search_enabled": , "is_schedule_enabled": , "id": } ] 7. addProfile Creates a new filtering policy. Authorization is required. Mandatory parameter: name - policy name Response: { "name": , "default": , "white_list_only": , "token": , "safe_search_enabled": , "is_schedule_enabled": , "id": } 8. removeProfile Deletes a filtering policy. Authorization is required. Mandatory parameter: profile_id - id of the policy that should be deleted. Response: null 9. renameProfile Renames a filtering policy. Authorization is required. Mandatory parameters: profile_id - policy id. name - policy name. Response: 10. categories Gets a list of available filtering categories. Authorization is required. Response: [ { "title": , "items": [{"title": , "id": }] } ] 11. userFilter Gets a list of filtering categories applied for a user. Authorization is required. Mandatory parameter: profile_id - policy id. Response: [, , ] 12. setFilterCat Changes filtering settings. Authorization is required. Mandatory parameters: profile_id - policy id. cat - category id. state - boolean value (add/remove the category from the filtering settings). Response: null 13. domains Gets a list of Allow/Denylisted domains for a certain filtering policy. Authorization is required. Mandatory parameters: profile_id - policy id. choice - domain type (available options: “black”, “white”, “alias”). Response: If the domain type is “black” or “white” [{"domain":,"id":}] If the domain type is “alias”: [{"domain":,"id":,"ip":}] 14. addDomain Adds a domain to the Allow/Denylist for a certain filtering policy. Authorization is required. Mandatory parameters: profile_id - policy ID. choice - domain type (available options: “black”, “white”, “alias”). domain – domain. Optional parameter: ip - IP address, the parameter should be used if the “alias” domain is being added. comment - adds a comment for a domain. Response: 15. removeDomain Deletes a domain from the Allow/Denylist for a certain filtering policy. Authorization is required. Mandatory parameters: profile_id - policy ID. choice - domain type (available options: “black”, “white”, “alias”). domain – domain. Response: null 16. clearDomains Clears the list of Allow/Denylisted domains for a certain filtering policy. Authorization is required. Mandatory parameters: profile_id - policy ID. choice - domain type (available options: “black”, “white”, “alias”). Response: null 17. updateNic Updates a dynamic IP. Authorization is required. Mandatory parameters: profile_id - policy ID. hostname - hostname. Response: 18. setWhiteListOnly Enables/disables the "Allow list only" mode. Authorization is required. Mandatory parameters: profile_id - policy ID. flag - enable/disable option (boolean value). Response: null 19. setSafeSearchEnabled Enables/disables "Safe Search mode" for Google and Bing. Authorization is required. Mandatory parameters: profile_id - policy ID. flag - boolean value (enable/disable option). Response: null 20. setSafeYoutubeEnabled Enables/disables "Safe Search mode" for Google and Bing. Authorization is required. Mandatory parameters: profile_id - policy ID. flag - boolean value (enable/disable option). Response: null 21. setBlockUnknownEnabled Enables/disables “Restricted YouTube mode”. Authorization is required. Mandatory parameters: profile_id - policy ID. flag - boolean value (enable/disable option). Response: null 22. multiSchedule Gets information on the filtering schedule for a certain policy. Authorization is required. Mandatory parameter: profile_id - policy ID. Response: [[, ], [, ]] 23. setSchedule Sets filtering schedule for a certain policy. Authorization is required. Mandatory parameters: profile_id - policy ID. segments - a list of segments for scheduling: [[, ], [, ]]. Response: [true] 24. setScheduleEnabled Enables/disables filtering schedule for a certain policy. Authorization is required Mandatory parameters: profile_id - policy ID. flag - boolean value (enable/disable option). Response: 25. profileScheduleActivity Gets the time left before a change of the filtering policy according to the filtering schedule. Authorization is required Mandatory parameter: profile_id - policy ID Response: [, ] Note: If the scheduling is turned off or there are no other states: mins_until_change = -1. 26. getProfile This method includes 3 functions, depending on the parameters. Authorization is required.: creates AgentInfo; gets AgentInfo status; updates AgentInfo policy Mandatory parameters for creating Agent info and getting a policy: uid - "" hostname - hostname. version - version. os_info - information on the OS. address - IP address. Mandatory parameters for getting the current policy of AgentInfo: uid - uid AgentInfo. hostname - "". version - "". os_info - "". address - "". Mandatory parameters for updating AgentInfo: uid - uid AgentInfo. hostname - new hostname. version - new version. os_info - new information on the OS. address - new IP address. Response: [, , ] 27. setProfile Sets a filtering policy for AgentInfo. Authorization is required Mandatory parameters: uid - uid AgentInfo. profile_id - policy ID. Response: null 28. feedback Sends user’s feedback. Authorization is required. Mandatory parameters: title - the subject line. message – user’s message. Response: null 29. getCategoriesDailyStats Gets daily categories stats of a policy. Authorization is required. Mandatory parameter: profile_id - policy ID. Optional parameters: lang - response language. categories_list - defines a list of categories. if it’s not set - the result will show all the categories. Response: {: } 30. getAdvertising Gets the information on promo. Authorization is required Response: {, } 31. getPlans Gets the list of available billing plans. Optional parameter: mobile - gets the Plans list, and determines whether to respond with mobile plans only. Boolean value. Response: { 'name': , 'code': , 'isMobile': , 'period': , 'trialPeriod': , 'price': , 'description': , } 32. getPlan Gets user’s billing plan. Authorization is required. Response: { 'name': , 'expired': , 'isMobile': , } 33. getAPCVersion Gets mobile app’s version: minimal supported and the current one. Optional parameter: tag - tag for getting the versions (the value “default” is set by default). Response: { "minimalSupported": , "current": }