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/v2v2 -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 available API methods:

• systemInfo - gets information about the system configuration

• myip - gets the current client’s IP

• testAuth - user’s authentication

• register - registers a new user

• userInfo - gets user information

• profiles - gets a list of available filtering profiles

• addProfile - creates a new filtering profile

• removeProfile - deletes a filtering profile

• renameProfile - renames a filtering profile

• categories - gets a list of available filtering categories

• userFilter - gets a list of filtering categories applied for a user

• setFilterCat - changes filtering settings

• domains - gets a list of white- and black-listed domains for a certain filtering profile

• addDomain - adds a domain to the white or black list for a certain filtering profile

• removeDomain - deletes a domain from a certain filtering profile

• clearDomains - clears the list of domains for a certain filtering profile

• updateNic - updates a dynamic IP

• setWhiteListOnly - enables/disables the “White list only” mode

• setSafeSearchEnabled - enables/disables “Safe Search mode” for Google and Bing

• setSafeYoutubeEnabled - enables/disables “Restricted YouTube mode”

• multiSchedule - gets information on the filtering schedule for a certain profile

• setSchedule - sets filtering schedule for a certain profile

• setScheduleEnabled - enables/disables filtering schedule for a certain profile

• profileScheduleActivity - gets the time left before a change of the filtering profile according to the filtering schedule

• getProfile - the method includes 3 functions, depending on the parameters:

• creates AgentInfo;

gets AgentInfo status;

updates AgentInfo profile

 

setProfile - sets a filtering profile for AgentInfo

feedback - sends user’s feedback

getCategoriesDailyStats - gets daily categories stats of a profile

getAdvertising - gets the information on promo

getPlans - gets the list of available billing plans

getPlan - gets the user’s billing plan

getAPCVersion - gets mobile app’s version: minimal supported (that should be forcefully updated) and the current one.

---

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‌

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. 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. Authorization is required.

Mandatory parameter:

• name - profile 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. Authorization is required.

Mandatory parameter:

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

Response:

null

null

---

renameProfile

Renames a filtering profile. Authorization is required. Mandatory parameters:

• profile_id - profile id.

  
  

• name - profile 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 - profile id.

Response:

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

---

setFilterCat

Changes filtering settings. Authorization is required. Mandatory parameters:

profile_id - profile 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-listed domains for a certain filtering profile. Authorization is required.

Mandatory parameters:

profile_id - profile 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 list for a certain filtering profile. Authorization is required.

Mandatory parameters:

profile_id - profile 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 list for a certain filtering profile. Authorization is required.

Mandatory parameters:

profile_id - profile ID.

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

domain – domain.

Response:

null

---

clearDomains

Clears the list of white-/black- listed domains for a certain filtering profile. Authorization is required.

Mandatory parameters:

profile_id - profile ID.

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

Response:

null

---

updateNic

Updates a dynamic IP. Authorization is required.

Mandatory parameters:

profile_id - profile ID.

hostname - hostname.

Response:

<IP address>

---

setWhiteListOnly

Enables/disables the “White list only” mode. Authorization is required. Mandatory parameters:

profile_id - profile ID.

flag - enable/disable option (boolean value).

Response:

null

---

setSafeSearchEnabled

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

Mandatory parameters:

profile_id - profile ID.

flag - boolean value (enable/disable option).

Response:

null

---

setSafeYoutubeEnabled

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

Mandatory parameters:

profile_id - profile ID.

flag - boolean value (enable/disable option).

Response:

null

---

setBlockUnknownEnabled

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

profile_id - profile ID.

flag - boolean value (enable/disable option).

Response:

null

---

multiSchedule

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

Mandatory parameter:

profile_id - profile ID.

Response:

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

---

setSchedule

Sets filtering schedule for a certain profile. Authorization is required Mandatory parameter:

profile_id - profile 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. Authorization is required

Mandatory parameter:

profile_id - profile ID.

flag - boolean value (enable/disable option).

Response:

<true|false>

---

profileScheduleActivity

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

Mandatory parameter:

profile_id - profile 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 profile

   
   

   Mandatory parameters for creating Agent info and getting a profile:

   
   

uid - ""

hostname - hostname.

version - version.

os_info - information on the OS.

address - IP address.

Mandatory parameters for getting the current profile 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 profile for AgentInfo. Authorization is required

Mandatory parameters:

uid - uid AgentInfo.

profile_id - profile 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. Authorization is required.

Mandatory parameter:

profile_id - profile 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 plans

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)>

}