API Reference
This reference documents the Peresvet ST controller REST API. Use it to integrate external systems, automate administrative operations, and access task, agent, network, file, report, and settings data without using the web interface.
Send every request to the controller. You do not need to contact agents directly: the controller manages them, sends commands, and collects execution results. External clients therefore use a single controller API, while the DPDK layer and agent network interfaces remain outside the public contract.
Paths on operation pages are relative to the OpenAPI basePath: /v1. Add this prefix to the controller address when making a request.
How to use this reference
The API section begins with this overview and continues into collections for users, tasks, agents, networks, files, and other operation groups. Collections and operations appear in the right-hand navigation, while the main page area shows the method, path, parameters, and responses for the selected operation.
Each operation includes its request contract, a parameter table, possible responses, and an example data structure. Types and descriptions come from the controller's Swagger annotations, so this reference reflects the controller's actual contract.
Basic workflow
First, create a session through the authentication endpoint. On success, the controller sets HttpOnly cookies that your browser or HTTP client must include in subsequent requests.
POST /v1/auth/login HTTP/1.1
Host: controller.example
Content-Type: application/json
{"email":"admin@example.com","password":"password"}
After authentication, use the same session when requesting controller resources.
GET /v1/tasks?count=10&page=1&key=id&order=desc HTTP/1.1
Host: controller.example
Cookie: accessToken=...
API collections
Section | Tag | Endpoints |
|---|---|---|
| System | meta | 3 |
| Authentication | auth | 4 |
| Users | users | 11 |
| Groups | groups | 6 |
| Agents | agents | 17 |
| Tasks | tasks | 43 |
| Task templates | task-templates | 6 |
| Networks | networks | 12 |
| Certificates | certificates | 6 |
| MAC addresses | macs | 6 |
| Files | files | 15 |
| Tunnels | tunnels | 9 |
| Applications | applications | 10 |
| Malware | malware | 13 |
| CVE | cve | 11 |
| Notifications | notifications | 3 |
| Settings | settings | 2 |
| AI administration | ai-admin | 5 |
| AI Gateway | ai-gateway | 29 |
| Compromised hosts | compromised-host | 1 |
| Dictionaries | dictionaries | 6 |
| Projects | projects | 7 |