Documentation — Stressthem API & Integration Guide

Quickstart

This guide walks you through launching your first stress test in under five minutes. You will need a registered account, a valid API key, and a target that you own or have explicit written authorization to test. The fastest path is to use the hosted dashboard for one-off tests and switch to the API or CLI for repeatable, automated workloads.

Quickstart checklist:
- Register an account at /register.php and verify your email.
- Generate an API key from the dashboard → Settings → API.
- Add a target and complete DNS TXT or HTTP file verification.
- Wait for the target status to flip to verified (usually instant).
- Launch your first 30-second UDP flood via the dashboard or the API.

Here is the minimum viable API call to launch a 30-second UDP flood:

            
# Set your API key (from dashboard → Settings → API)
export STRESSTHEM_API_KEY="sk_live_a1b2c3d4e5f6..."

# Launch a 30-second UDP flood against a verified target
curl -X POST https://api.stressthem.example/v1/jobs \
  -H "Authorization: Bearer $STRESSTHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target":   "stress-test.lab",
    "method":   "UDP-FLOOD",
    "port":     80,
    "duration": 30,
    "power":    50,
    "request_id": "ci-run-42"
  }'
          

The response is JSON and contains a job ID you can poll for status, or you can subscribe to a webhook to receive a callback when the job completes. The request_id is optional but recommended — it makes the launch idempotent, so a retried CI run will not double-launch.

Authentication

All API requests are authenticated with a Bearer token in the Authorization header. Tokens are account-scoped and inherit the rate limits and method allowlist of the plan that issued them. Tokens can be scoped further at creation time to restrict which methods they can launch, which targets they can target, and which IP ranges they can be called from.

Treat API keys like passwords. Never embed them in client-side JavaScript, mobile apps or other code that can be reverse-engineered. For server-to-server integrations, store the key in a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) and inject it as an environment variable at runtime. Rotate keys at least every 90 days and immediately if you suspect a leak.

            
# Header format
Authorization: Bearer sk_live_a1b2c3d4e5f6...

# Generate a new key (CLI)
stressthem api-keys create \
  --name "ci-pipeline" \
  --scope "jobs:write,jobs:read" \
  --methods "UDP-FLOOD,TCP-SYN,HTTP-GET"
          

Target Verification

Before any traffic can be sent to a target, the target must be verified as owned by the account that wants to test it. Stressthem supports three verification methods: a DNS TXT record, an HTTP challenge file, or a signed cloud-provider ownership token. Targets must be re-verified every 30 days; the dashboard will show a yellow warning when re-verification is due within 7 days.

Verification is enforced at the API gateway, not at the launch endpoint. This means an unverified target will be rejected at the API call itself, before any traffic is queued. The verification status is exposed in the API so you can programmatically detect targets that need re-verification and trigger a re-check before they expire.

DNS TXT verification

Add a TXT record to the target domain's DNS zone containing your per-account token. The token is unique per account and never changes; you can find it in the dashboard under Settings → Verification.

# Add this TXT record to your DNS zone stress-test.lab. IN TXT "stressthem-verify=acc_7f3e9b2c"

HTTP file verification

Serve a plain-text file at a well-known URL containing your account token. The file must return HTTP 200 with a body that exactly matches the token, with no trailing whitespace or HTML wrapping.

# Place this file at https://stress-test.lab/.well-known/stressthem.txt acc_7f3e9b2c

REST Endpoints

The REST API is organized around predictable resource-oriented URLs, standard HTTP verbs, JSON-encoded request and response bodies, and standard HTTP response codes. The base URL is https://api.stressthem.example/v1. All endpoints require authentication unless marked otherwise.

POST /v1/jobs — Launch a stress job

Queues a new stress job. Returns the job object with initial status queued. Once the job is allocated to amplification nodes and the first packet is sent, the status flips to running. On completion the status becomes completed (target stayed responsive), target_down (target stopped responding during the test) or error (infrastructure-side issue).

            
POST /v1/jobs
{
  "target":     "stress-test.lab",     # required, must be verified
  "method":     "UDP-FLOOD",          # required, see /methods
  "port":       80,                   # optional, default 80
  "duration":   30,                   # required, seconds (1-3600)
  "power":      50,                   # 1-100, % of plan capacity
  "request_id": "ci-run-42",           # optional, idempotency key
  "spoof":      false                   # optional, requires plan support
}

# Response 201 Created
{
  "id":         "job_4827a9c1",
  "status":     "queued",
  "target":     "stress-test.lab",
  "method":     "UDP-FLOOD",
  "duration":   30,
  "created_at": "2026-08-06T12:34:56Z",
  "webhook_url": "https://api.stressthem.example/v1/jobs/job_4827a9c1/events"
}
          

GET /v1/jobs/{id} — Job status & telemetry

Returns the current status of a job plus live telemetry: instantaneous throughput in Gbps, packet rate in pps, target RTT in milliseconds, and a rolling error-ratio. For completed jobs, also includes summary statistics and links to downloadable PCAP and HAR captures (plan-dependent).

            
GET /v1/jobs/job_4827a9c1

# Response 200 OK
{
  "id":     "job_4827a9c1",
  "status": "running",
  "progress": {
    "elapsed":   12.4,
    "remaining": 17.6,
    "gbps":     48.7,
    "pps":      6120000,
    "rtt_ms":   14.2,
    "err_ratio": 0.0021
  }
}
          

Webhooks

Subscribe to job lifecycle events by registering a webhook URL. Stressthem will POST a signed JSON payload to your URL on each event. The signature is HMAC-SHA256 of the raw body using your webhook secret, sent in the X-Stressthem-Signature header. Always verify the signature before acting on the payload.

Event types: job.queued, job.running, job.completed, job.target_down, job.error.

            
POST https://your-app.com/webhooks/stressthem
{
  "event":     "job.completed",
  "job_id":    "job_4827a9c1",
  "target":    "stress-test.lab",
  "method":    "UDP-FLOOD",
  "duration":  30,
  "outcome":   "completed",
  "peak_gbps": 52.4,
  "peak_pps":  7120000,
  "captures": [
    { "type": "pcap", "url": "https://...", "expires": "2026-08-13T12:34:56Z" },
    { "type": "har",  "url": "https://...", "expires": "2026-08-13T12:34:56Z" }
  ],
  "timestamp": "2026-08-06T12:35:26Z"
}
          

Official SDKs

Official SDKs are available for Python, Go, Node.js and shell. They handle authentication, retries with exponential backoff, idempotency and pagination automatically. The shell SDK is a single-file script with no dependencies beyond curl and jq, suitable for CI/CD pipelines.

Python

            
from stressthem import Client

client = Client(api_key="sk_live_...")

job = client.jobs.launch(
    target="stress-test.lab",
    method="HTTP-GET",
    duration=60,
    power=30,
    request_id="ci-run-42",
)

for event in client.jobs.stream(job.id):
    print(f"[{event.status}] {event.gbps:.1f} Gbps · {event.pps/1e6:.2f} Mpps")
          

Node.js

            
import { Stressthem } from '@stressthem/sdk';

const client = new Stressthem({ apiKey: process.env.STRESSTHEM_API_KEY });

const job = await client.jobs.launch({
  target: 'stress-test.lab',
  method: 'TCP-SYN',
  duration: 60,
  power:   50,
  requestId: 'ci-run-42',
});

for await (const ev of client.jobs.stream(job.id)) {
  console.log(`[${ev.status}] ${ev.gbps} Gbps`);
}
          

Shell / CLI

            
# Install
pipx install stressthem-cli

# Authenticate
stressthem auth login --key "sk_live_..."

# Launch and stream telemetry
stressthem boot \
  --target   stress-test.lab \
  --method   UDP-FLOOD \
  --duration 60 \
  --power    80 \
  --stream
          

Error Codes

Stressthem uses conventional HTTP response codes: 2xx for success, 4xx for client errors (bad request, unauthorized, target not verified, plan limit reached), 5xx for server errors. Errors return a JSON body with error.code and error.message fields. The most common error codes are listed below.

401 unauthorized — Missing or invalid API key.
403 target_not_verified — Target has not completed verification.
403 method_not_allowed — Method not in plan allowlist.
409 duplicate_request — A job with this request_id already exists.
422 invalid_parameter — Port out of range, duration too long, etc.
429 rate_limited — Too many launches per minute; back off and retry.
503 capacity_exceeded — All amplification nodes busy; retry shortly.

Compliance note. Every API call is logged to an immutable audit trail retained for 18 months. Account owners can export their own audit trail as JSONL or CSV. Do not share API keys between team members — create per-person keys so that audit entries attribute launches to specific individuals.