Accessing the API

Every API function accepts a number of parameters and returns a return value. If you are using an API library, handling of these values is done automatically by the library. However, If you want to call the functions directly, you need to process them properly.

Input parameters

The parameters of every function can be sent either as GET or POST variables. For example, a call to the /settings/dns/get function can be performed as follows:

    url: '',
    type: 'POST', // can be either "POST" or "GET"
    headers: {
        'Authorization': 'Basic ' + btoa('API-KEY' + ':' + 'API-KEY-PASSWORD')
    data: {
        name: "",

If "Content-Type: application/json" header is added to the request then parameters can be also sent as JSON. For example:

curl -X POST \
    -H "Content-type: application/json" \ \
    -d '{"name": "", "ns" : ["", ""]}'

Some parameters have a default value and can be safely omitted, unless a value other than the default needs to be sent. Other parameters are required and must be passed with the function call.

Every parameter also has a specified data type, which indicates how the value should be sent:

  • boolean - a true or false value. Values 0 and false are treated as Boolean false, all others are treated as Boolean true. Your application can use, for example 0 for false and 1 for true, or strings "true" and "false".
  • integer - a string that can be parsed into an integer value. Possible examples are 0, 333, -10. Values such as abc, 1e3, 0x2F or 1.25 are incorrect.
  • float - a string that can be parsed into a number, such as 1.20. Integer values (without the decimal part) are also accepted.
  • string - any string value.
  • array of strings - a string with values separated by commas, semicolons or whitespace. Possible values are, or 20.05. 20.10..

Return values

Every function returns data in a JSON format. For cross-domain calls, JSONP is supported and the JSONP wrapper must be specified in the callback parameters. Libraries such as jQuery handle all necessary JSONP setup automatically.

Upon successful function execution, a structure is returned which looks as follows:

    ok: 1,
    status: 0,
    error: "",
    data: ...,     // The function return value
    errtype: ""

Nonzero value of the field ok indicates a successful function execution. The actual data is returned in the data field, which can hold a single value or a further structure. For example, the function /account/balance returns a single value:

    data: 120.75

The function /settings/dns/get returns a structure with two fields:

    data: {
        ns1 : "",
        ns2 : ""

And the function /category/list returns an array:

    data: [
            auctionCategoryId : "10.",
            description : "Generic domains",
            auctionCount: 45,
            marketCount: 1489

Handling errors

A function call can also result in an error. In this case, the status and error fields of the return structure will be filled:

    ok: 0,
    status: 500,
    error: "Invalid authentication data",
    data: null,
    errtype: "Error_API_Authorization"

The field status holds a numeric code for the error, errtype its type, and the field error its textual description. In such case, no data is returned in the data field.

The list of error codes and types can be found here.