Documentation

API Reference

Integrate your own applications with the RETRO//STRESS REST API to automate stress-test deployments, query active tests, and manage your chains programmatically.

Overview

The RETRO//STRESS API exposes two surface areas:

Legacy endpoint — a single GET /api/start that accepts URL query parameters. Designed for compatibility with existing scripts and simple integrations.
REST API v1 — a structured /api/v1/… namespace using JSON bodies and Bearer token authentication. Recommended for all new integrations.

All v1 endpoints return a consistent API response envelope. Rate limits apply per API key across the board.

💡

The base URL for all calls is https://retrostress.net. All v1 requests must include the Authorization: Bearer <api_key> header unless noted otherwise.

Authentication

API keys are generated from the API Keys tab in your panel. Two mechanisms are supported:

Method	How to Use	Applies To
`Bearer Token`	Include `Authorization: Bearer <api_key>` in the HTTP header.	All `/api/v1/` endpoints
Query Parameter	Pass `?key=<api_key>` in the URL.	Legacy `GET /api/start` only

⚠️

API keys are shown only once upon creation. Store them securely — they cannot be retrieved later.

Response Format

Every v1 response is wrapped in a consistent envelope:

Envelope Schema

{
  "success": true,           // boolean — false on any error
  "data":    { ... } | null, // endpoint-specific payload, null on error
  "message": "…",            // optional human-readable message
  "errors":  ["…"]           // present only when success is false
}

Endpoints

GET /api/start No Auth Header

Legacy endpoint for launching one or more tests via URL query parameters. Authenticate using the key query parameter instead of a Bearer header.

Query Parameters

Parameter	Type	Required	Description
`key`	string	required	Your API key.
`target`	string	required	Destination IP or hostname.
`port`	integer	required	Target port (1–65535).
`time`	integer	required	Duration in seconds.
`method`	string	required	Method name (e.g. `TCP-SYN`).
`concurrent`	integer	optional	Number of simultaneous tests to launch. Default: `1`, max: `100`.

Example request

GET https://retrostress.net/api/start?key=rs_xxx&target=1.2.3.4&port=80&time=60&method=TCP-SYN

Response — 201 Created

{
  "success": true,
  "message": "Started 1 test(s) successfully.",
  "data": {
    "id": 42,
    "target": "1.2.3.4",
    "port": 80,
    "duration": 60,
    "stopped": false,
    "createdAt": "2026-02-26T22:00:00Z",
    "expiresAt":  "2026-02-26T22:01:00Z",
    "secondsRemaining": 58,
    "method": { "id": 1, "name": "TCP-SYN", "description": "…", "layer": 4 }
  }
}

POST /api/v1/tests Bearer Token

Launch one or more tests. Accepts a JSON body. Either methodId or method (name) must be provided; when both are given, methodId takes priority.

Request Body

Field	Type	Required	Description
`target`	string	required	Destination IP or hostname.
`port`	integer	optional	Target port (1–65535).
`duration`	integer	required	Duration in seconds (>= 1).
`methodId`	integer	optional*	Numeric method ID. Required if `method` is omitted.
`method`	string	optional*	Method name (case-insensitive). Required if `methodId` is omitted.
`concurrent`	integer	optional	Tests to launch simultaneously. Default: `1`, max: `100`.
`chainId`	integer	optional	Your saved chain ID. When set, launches a chain test. Requires the Advanced Methods plan feature.
`customId`	string	optional	Arbitrary label you can attach to the test for your own tracking.
`customParameters`	object	optional	Key-value pairs of method-specific parameters.

Example request

POST /api/v1/tests
Authorization: Bearer rs_xxx
Content-Type: application/json

{
  "target": "1.2.3.4",
  "port": 80,
  "duration": 120,
  "method": "TCP-SYN",
  "concurrent": 3
}

Response — 201 Created

{
  "success": true,
  "message": "Started 3 test(s) successfully.",
  "data": { /* TestResponse object for the last launched test */ }
}

DELETE /api/v1/tests/{id} Bearer Token

Stop a specific running test by its integer id. Returns 404 if the test does not exist, is already stopped, or belongs to a different account.

Example

DELETE /api/v1/tests/42
Authorization: Bearer rs_xxx

Response — 200 OK

{ "success": true, "message": "Test stopped successfully.", "data": null }

DELETE /api/v1/tests Bearer Token

Stop all active tests belonging to your account in a single call.

Response — 200 OK

{
  "success": true,
  "message": "Stopped 3 test(s).",
  "data": { "stoppedCount": 3 }
}

GET /api/v1/tests/active Bearer Token

Returns an array of all currently running tests for your account.

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "id": 42,
      "target": "1.2.3.4",
      "port": 80,
      "duration": 120,
      "customId": null,
      "stopped": false,
      "createdAt": "2026-02-26T22:00:00Z",
      "expiresAt":  "2026-02-26T22:02:00Z",
      "secondsRemaining": 90,
      "method": { "id": 1, "name": "TCP-SYN", "description": "…", "layer": 4 }
    }
  ]
}

GET /api/v1/methods Bearer Token

Lists all attack methods available to your account. Optionally filter by OSI layer.

Query Parameters

Parameter	Type	Required	Description
`layer`	integer	optional	Filter to Layer `4` or Layer `7` methods only. Omit to return all.

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "TCP-SYN",
      "description": "High-rate SYN flood.",
      "layer": 4,
      "load": 2.5,
      "parameters": [
        { "name": "pps", "defaultValue": "100000" }
      ]
    }
  ]
}

GET /api/v1/chains Bearer Token

Returns all chain definitions saved to your account. Use the returned id as the chainId field when launching a test.

💡

Chains are only available on plans with Advanced Methods. See the Chain Builder Guide for how to create them.

Response — 200 OK

{
  "success": true,
  "data": [
    {
      "id": 7,
      "name": "tcp-handshake",
      "mode": "scaled",
      "createdAt": "2026-01-10T14:22:00Z"
    }
  ]
}

Error Codes

The API uses standard HTTP status codes. The message field in the response envelope always contains a human-readable explanation.

Status	Meaning	Common cause
`400`	Bad Request	Missing or invalid parameters in the request body or query string.
`401`	Unauthorized	API key missing, invalid, or expired.
`403`	Forbidden	No active subscription, or concurrent test limit reached for your plan.
`404`	Not Found	Requested method, chain, or test does not exist (or belongs to another account).
`429`	Too Many Requests	Rate limit exceeded. Back off and retry after a short delay.
`500`	Server Error	Unexpected server-side failure. Contact support if the issue persists.
`503`	Service Unavailable	No attack servers currently available. Retry shortly.

⚠️

404 is returned intentionally for both "not found" and "access denied" on test stop, to prevent account enumeration.