How to Use the API?

What is an API?

An API (Application Programming Interface) is an interface that allows two applications to interact with each other using predefined sets of commands.

The API enables the management of objects within ordered services—such as adding and removing domains, updating configuration parameters, retrieving attack history, and more. Through this interaction, you can also retrieve or add information to your personal account, automatically extract service lists, manage “black” and “white” user lists, and much more.

Detailed descriptions of commands and data models for requests and responses can be found at the following addresses:

How to Create a Token?

To ensure secure access to information from your personal account, authentication is implemented based on tokens.

When requesting information from your device, it will be authenticated using an authentication token, just as you would use a login and password to access your personal account.

Go to the new control panel using any of the options available in your personal account. Open the Users tab in the top-left section of the screen. This will reveal the menu options: Users, Roles, and API Tokens.

Note

Tokens created in the new personal account are valid indefinitely.

Click on API Tokens.

On the newly opened page, you can add or delete tokens.

To add a new token, click + Add Token.

Select access permissions for the token. You can add a description in the Description field or leave it blank.

Click Add Token.

Be sure to copy the generated token — click Copy to Clipboard and Close.

A new row with the status “Active” will appear in the token table.

You can delete expired tokens by selecting them and clicking Delete Selected.

Each token has a unique ID, which can be used to identify actions performed with that token (e.g., creation, deletion) in the request log.

API Interface Description

The API uses a REST interface and only built-in HTTP functions, which are understood by any standard HTTP client.

  • For ease of proxying and monitoring, object identification data is always passed as part of the URL path.
Example

GET /user/service/1/domain/2

  • 1 is the service ID;
  • 2 is the domain ID.

    • For lists in read commands, request parameters with a repeating key are used.
    Example

    GET /user/service/1/domain/stats?domain_id=3&domain_id=6.

    • All other data for modifying commands is sent in the request body in JSON format.
    • Responses are always returned in JSON format, including error messages, except for conversion commands.
    Request Size Limits:
    • Maximum request body size: 1 MB
    • Maximum header size: 8 KB
    Error Handling in the API

    There are two levels of error indication in the system:

    1. HTTP status code
    2. Error code list in the response
    • An HTTP status other than “200” indicates a critical error from either the user or the system.
    • If the HTTP status is “200”, the error list contains only non-critical errors (warnings).

    If the API returns a critical error, no actions have been taken on the objects, and the request can be retried, possibly with corrected data.

    • Example: If a command requires a domain name, but an invalid string (e.g., with spaces) is submitted, the API will return “400” (“Bad Request”).

    If at least one non-critical error appears in the list, it means that some operations have already been performed, possibly on physical hardware. These errors do not cause object malfunctions but may require additional actions.

    • Example: If an SSL certificate installation returns a non-critical error, it means that while the certificate format is correct, the system refuses to install it for the given domain because the domain name does not match the certificate records.
    HTTP Methods and Their Actions
    HTTP MethodAction
    POSTCreate a new object
    GETRetrieve object information
    PUTUpdate object information
    DELETEDelete an object
    Example

     { “statusCode”: 400, “error”: “Bad Request”, “message”: “Invalid request params input” }

    HTTP Response Status Codes
    Status CodeDescription
    200Request successfully executed
    400Invalid command input data
    403Command or input data is not allowed for the specified token
    404Command not defined in the system
    405Method not applicable to this command
    501This command is under development
    503System functionality is currently unavailable or request limit exceeded
    500+Internal system errors
    Example

     { “error_list”: [{ “type”: “SSL”, “code”: “INVALID_CERT_KEY_PAIR” }] }

    API Authentication and Token Usage

    Most commands require authentication via an API token. The token is passed using the Cookie header with the name api_access_token.

    Getting Started with API Token Authentication

    Most commands require authentication via an API token. The API token must be passed in the Cookie header with the name api_access_token.

    To start working with the API, begin by creating a token.

    To test requests, you can open any endpoint in the Swagger documentation and enter the active token value in the cookie field as api_access_token=eyJhb…. After filling in all other endpoint parameters, click the “Try it out” button, which will generate a curl request string.

    The curl string is generated for Linux systems. On Windows, all ' (single quotes) must be replaced with " (double quotes), and inner quotes must be escaped. Alternatively, you can use a Linux-like terminal, such as Git Bash.

    In the API documentation, you can view the data model for each command’s response and complex parameters by switching to the “Model” tab. The models specify field types and provide brief descriptions.