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:
- StormWall API v1 — https://api.stormwall.pro/documentation
- StormWall API v2 — https://apiv2.stormwall.pro/swagger-public
Without authentication, Swagger works in demo mode — requests are not executed on the server.
For interactive work:
- Get an API token in your personal account.
- Open developer tools (F12 → Console).
- Execute the following command, replacing TOKEN with your key:
document.cookie = "api_access_token=TOKEN; path=/";
Now the interface will execute real requests.
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.
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.
GET /user/service/1/domain/2
- For lists in read commands, request parameters with a repeating key are used.
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:
- HTTP status code
- 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 Method | Action |
| POST | Create a new object |
| GET | Retrieve object information |
| PUT | Update object information |
| DELETE | Delete an object |
{ “statusCode”: 400, “error”: “Bad Request”, “message”: “Invalid request params input” }
HTTP Response Status Codes
| Status Code | Description |
| 200 | Request successfully executed |
| 400 | Invalid command input data |
| 403 | Command or input data is not allowed for the specified token |
| 404 | Command not defined in the system |
| 405 | Method not applicable to this command |
| 501 | This command is under development |
| 503 | System functionality is currently unavailable or request limit exceeded |
| 500+ | Internal system errors |
{ “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.
