Skip to main content

Release 1.0

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":"para m1"}}'


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"}
}

Сurrently

Table of available APImethods:
methods:

    # Value Description 1 systemInfo - getsGets information about the system configuration

    2 myip - getsGets the current client’s IP

    3 testAuth - user’User’s authentication

    4 register - registersRegisters a new user

    5 userInfo - getsGets user information

    6 profiles - getsGets a list of available filtering profilespolicies

    7 addProfile - createsCreates a new filtering profilepolicy

    8 removeProfile - deletesDeletes a filtering profilepolicy

    9 renameProfile - renamesRenames a filtering profilepolicy

    10 categories - getsGets a list of available filtering categories

    11 userFilter - getsGets a list of filtering categories applied for a user

    12 setFilterCat - changesChanges filtering settings

    13 domains - getsGets a list of white- and black-listedAllow/Denylisted domains for a certain filtering profilepolicy

    14 addDomain - addsAdds a domain to the white or black listAllow/Denylist for a certain filtering profilepolicy

    15 removeDomain - deletesDeletes a domain from a certain filtering profilepolicy

    16 clearDomains - clearsClears the list of domains for a certain filtering profilepolicy

    17 updateNic - updatesUpdates a dynamic IP

    18 setWhiteListOnly - enables/Enables/disables the “White"Allow list only”only" mode

    19 setSafeSearchEnabled - enables/Enables/disables “"Safe Search mode”mode" for Google and Bing

    20 setSafeYoutubeEnabled - enables/Enables/disables “"Restricted YouTube mode”mode"

    21 multiSchedule - getsGets information on the filtering schedule for a certain profilepolicy

    22 setSchedule - setsSets filtering schedule for a certain profilepolicy

    23 setScheduleEnabled - enables/Enables/disables filtering schedule for a certain profilepolicy

    24 profileScheduleActivity - getsGets the time left before a change of the filtering profilepolicy according to the filtering schedule 25 getProfile

    -AgentInfo, thegets methodAgentInfo includesstatus 3or functions,updates AgentInfo policy depending on the parameters:parameters

      creates

      AgentInfo;26 setProfile

      gets AgentInfo status;

      updates AgentInfo profile


      - sets

      Sets a filtering profilepolicy for AgentInfo

      27 feedback - sendsSends user’s feedback

      28 getCategoriesDailyStats - getsGets daily categories stats of a profilepolicy

      29 getAdvertising - getsGets the information on promo

      Available methods:

      systemInfo

      Gets information on the system settings.

      Response:

      {
"public_dns": <public_dns>,
"nxdomain": <nxdomain>,
"blockpage": <blockpage>,
"blockpage_token": <blockpage_token>,
"blockapi": <blockapi>
}
      myip

      Gets current client’s IP.

      Response:

      <ip address>
      testAuth

      User’s authentication.

      Mandatory parameters:

      • username - client’s username.
      • password - client’s password.

      Response:

      <true|false>
      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, <error>]
      userInfo

      Gets user information. Authorization is required.

      Response:

      {
"plan": {
"name": <plan.name>,
"code": <plan.code>,
"features": <features>
},
"tz": <timezone_offset / 3600>,
"tz_minutes": <timezone_offset / 60>
}
      profiles

      Gets a list of available filtering profiles.policies. Authorization is required.

      Response:

      [
{
"name": <name>,
"default": <true|false>,
"white_list_only":<true|false>,
"token": <token>,
"safe_search_enabled": <true|false>,
"is_schedule_enabled": <true|false>,
"id": <id>
}
]
      addProfile

      Creates a new filtering profile.policy. Authorization is required.

      Mandatory parameter:

      • name - profilepolicy name

      Response:

      {
"name": <name>,
"default": <true|false>,
"white_list_only": <true|false>,
"token": <token>,
"safe_search_enabled": <true|false>,
"is_schedule_enabled": <true|false>,
"id": <id>
}
      removeProfile

      Deletes a filtering profile.policy. Authorization is required.

      Mandatory parameter:

      • profile_id - id of the profilepolicy that should be deleted.

      Response:

      null
      renameProfile

      Renames a filtering profile.policy. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy id.
      • name - profilepolicy name.

      Response:

      <name>
      categories

      Gets a list of available filtering categories. Authorization is required.

      Response:

      [
{
"title": <group1>,
"items": [{"title": <item1>, "id": <id>}]
}
]
      userFilter

      Gets a list of filtering categories applied for a user. Authorization is required.

      Mandatory parameter:

      profile_id - profilepolicy id.

      Response:

      [<cat_id1>, <cat_id2>, <cat_id3>]
      setFilterCat

      Changes filtering settings. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy id.
      • cat - category id.
      • state - boolean value (add/remove the category from the filtering settings).

      Response:

      null
      domains

      Gets a list of white- and black-listedAllow/Denylisted domains for a certain filtering profile.policy. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy id.
      • choice - domain type (available options: “black”, “white”, “alias”).

      Response:

      If the domain type is “black” or “white”

      [{"domain":<domain>,"id":<id>}]

      If the domain type is “alias”:

      [{"domain":<domain>,"id":<id>,"ip":<ip>}]
      addDomain

      Adds a domain to the white or black listAllow/Denylist for a certain filtering profile.policy. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy 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:

      <id of added domain>
      removeDomain

      Deletes a domain from the white or black listAllow/Denylist for a certain filtering profile.policy.

      Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • choice - domain type (available options: “black”, “white”, “alias”).
      • domain – domain.

      Response:

      null
      clearDomains

      Clears the list of white-/black- listedAllow/Denylisted domains for a certain filtering profile.policy.

      Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • choice - domain type (available options: “black”, “white”, “alias”).

      Response:

      null
      updateNic

      Updates a dynamic IP.

      Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • hostname - hostname.

      Response:

      <IP address>
      setWhiteListOnly

      Enables/disables the “White"Allow list only”only" mode. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • flag - enable/disable option (boolean value).

      Response:

      null
      setSafeSearchEnabled

      Enables/disables “"Safe Search mode”mode" for Google and Bing. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • flag - boolean value (enable/disable option).

      Response:

      null
      setSafeYoutubeEnabled

      Enables/disables “"Safe Search mode”mode" for Google and Bing. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • flag - boolean value (enable/disable option).

      Response:

      null
      setBlockUnknownEnabled

      Enables/disables “Restricted YouTube mode”. Authorization is required.

      Mandatory parameters:

      • profile_id - profilepolicy ID.
      • flag - boolean value (enable/disable option).

      Response:

      null
      multiSchedule

      Gets information on the filtering schedule for a certain profile.policy. Authorization is required.

      Mandatory parameter:

      • profile_id - profilepolicy ID.

      Response:

      [[<offset1>, <true|false>], [<offset2>, <true|false>]]
      setSchedule

      Sets filtering schedule for a certain profile.policy. Authorization is requiredrequired.

      Mandatory parameter:

      • profile_id - profilepolicy ID.
      • segments - a list of segments for scheduling: [[<offset1>, <true|false>], [<offset2>, <true|false>]].

      Response:

      [true]
      setScheduleEnabled

      Enables/disables filtering schedule for a certain profile.policy. Authorization is required

      Mandatory parameter:

      • profile_id - profilepolicy ID.
      • flag - boolean value (enable/disable option).

      Response:

      <true|false>
      profileScheduleActivity

      Gets the time left before a change of the filtering profilepolicy according to the filtering schedule. Authorization is required

      Mandatory parameter:

      • profile_id - profilepolicy ID

      Response:

      [<true|false>, <mins_until_change>]

      Note:

      If the scheduling is turned off or there are no other states: mins_until_change = -1.

      getProfile

      This method includes 3 functions, depending on the parameters. Authorization is required.:

      1. creates AgentInfo;

      2. gets AgentInfo status;

      3. updates AgentInfo profilepolicy

      Mandatory parameters for creating Agent info and getting a profile:policy:

      • uid - ""
      • hostname - hostname.
      • version - version.
      • os_info - information on the OS.
      • address - IP address.

      Mandatory parameters for getting the current profilepolicy 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:

      [<uid>, <token>, <profile_id>]
      setProfile

      Sets a filtering profilepolicy for AgentInfo. Authorization is required

      Mandatory parameters:

      • uid - uid AgentInfo.
      • profile_id - profilepolicy ID.

      Response:

      null
      feedback

      Sends user’s feedback. Authorization is required.

      Mandatory parameters:

      • title - the subject line.
      • message – user’s message.

      Response:

      null
      getCategoriesDailyStats

      Gets daily categories stats of a profile.policy. Authorization is required.

      Mandatory parameter:

      • profile_id - profilepolicy 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:

      {<category_name>: <value>}
      getAdvertising

      Gets the information on promo. Authorization is required

      Response:

      {<strAdvUrl>, <strImageUrl>}
      getPlans

      Gets the list of available billing plansplans.

      Optional parameter:

      • mobile - gets the Plans list, and determines whether to respond with mobile plans only. Boolean value.

      Response:

      {
'name': <plan name>,
'code': <plan code>,
'isMobile': <is mobile plan>,
'period': <period>,
'trialPeriod': <is trial>,
'price': <price>,
'description': <path>,
}
      getPlan

      Gets user’s billing plan. Authorization is required.

      Response:

      {
'name': <plan name>,
'expired': <expired_days>,
'isMobile': <true|false>,
}
      getAPCVersion

      Gets mobile app’s version: minimal supported (that should be mandatorily updated) and the current one.

      Optional parameter:

      • tag - tag for getting the versions (the value “default” is set by default).

      Response:

      {
"minimalSupported": <minimum supported version (integer, non-negative number)>,
"current":<current version of the mobile agent (integer, non-negative number)>
}