Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/binary-person/rammerhead/llms.txt

Use this file to discover all available pages before exploring further.

Rammerhead exposes a set of HTTP endpoints for managing proxy sessions and retrieving runtime information. Most endpoints are plain GET requests that accept query parameters and return plain-text responses. The /syncLocalStorage endpoint uses POST with a JSON body. All endpoints are served on the same port as the proxy itself (default 8080). No special headers are required.

​
Authentication

When config.password is set, endpoints that create, edit, or delete sessions require a pwd query parameter matching the configured password. The /needpassword endpoint lets clients check whether a password is required before prompting the user.
Requests to password-protected endpoints without a valid pwd value receive a 403 Forbidden response.

​
GET /needpassword

Returns whether the server requires a password to create sessions. 
curl http://localhost:8080/needpassword
Response: plain text true or false.
ValueMeaning
trueA password is required for session creation.
falseNo password is configured.

​
GET /newsession

Creates a new proxy session and returns its ID. 
curl "http://localhost:8080/newsession?pwd=yourpassword"
​
pwd
string
Required when config.password is set. Must match the server-configured password exactly.
Response: a 32-character hex session ID (UUID v4 without hyphens), e.g. a3f2c1d4e5b6a7f8c9d0e1f2a3b4c5d6. The session is immediately persisted to the session store. If restrictSessionToIP is true in config.js, the session is bound to the IP address of the creating request and will reject proxied traffic from other IPs.
Store the returned session ID. It is required for all subsequent session operations and for constructing proxied URLs.

​
GET /editsession

Updates settings on an existing session. 
curl "http://localhost:8080/editsession?id=<sessionId>&httpProxy=myproxy:8888&enableShuffling=1"
​
id
string
required
The session ID returned by /newsession.
​
httpProxy
string
An upstream HTTP proxy to route the session’s traffic through, in host:port format. If you include an http:// prefix it is stripped automatically. Omit this parameter entirely (or leave it empty) to clear any previously set upstream proxy.
​
enableShuffling
string
Controls URL shuffling for the session. Pass 1 to enable (generates a new shuffle dictionary if one does not already exist) or 0 to disable (clears the existing dictionary).
Response: plain text Success, or a 400 Bad Request if the session ID is missing or unknown.
When httpProxy is omitted, the upstream proxy is set to null (disabled). If you want to leave an existing proxy unchanged while only toggling shuffling, you must re-supply the httpProxy value.

​
GET /deletesession

Deletes a session from the session store. 
curl "http://localhost:8080/deletesession?id=<sessionId>&pwd=yourpassword"
​
id
string
required
The session ID to delete.
​
pwd
string
Required when config.password is set.
Response: plain text Success if the session was found and deleted, or not found if no session with that ID exists.

​
GET /sessionexists

Checks whether a session ID is present in the session store. 
curl "http://localhost:8080/sessionexists?id=<sessionId>"
​
id
string
required
The session ID to check. Returns a 400 Bad Request if this parameter is absent.
Response: plain text exists or not found.
Use this endpoint before constructing a proxy URL to confirm a session is still live, especially after long idle periods when sessions may have expired from the store.

​
GET /mainport

Returns the port number the proxy is listening on. 
curl http://localhost:8080/mainport
No parameters. Response: the port as a plain-text integer string, e.g. 8080. This is useful in reverse-proxy setups where getServerInfo is overridden in config.js and the effective port may differ from the default.

​
GET /api/shuffleDict

Returns the URL shuffle dictionary for a session that is currently open (actively proxying). 
curl "http://localhost:8080/api/shuffleDict?id=<sessionId>"
​
id
string
required
The session ID. The session must be currently open in memory (i.e. a proxied tab is actively using it). Returns a 400 Bad Request if the session is not open.
Response: a JSON-encoded string containing the 64-character shuffle dictionary for the session, or an empty body if URL shuffling is not enabled for that session. 
"q7Km3TxR..."
This endpoint queries openSessions, not the persistent session store. A session only appears in openSessions while a proxied page is actively connected. Sessions that have been created but not yet used will not be found here.

​
POST /syncLocalStorage

Synchronises localStorage data between the client and server for a given session and origin. This endpoint powers Rammerhead’s cross-tab localStorage persistence feature. Disable this endpoint by setting disableLocalStorageSync: true in config.js. When disabled, the endpoint returns 404. 
curl -X POST \
  "http://localhost:8080/syncLocalStorage?sessionId=<sessionId>&origin=https%3A%2F%2Fexample.com" \
  -H "Content-Type: application/json" \
  -d '{"type":"sync","fetch":true}'
​
sessionId
string
required
The session ID. The session must be open. Returns 400 if missing or not found.
​
origin
string
required
The proxied origin whose localStorage is being synced, URL-encoded (e.g. https%3A%2F%2Fexample.com). Returns 400 if absent.
The request body must be a JSON object. The type field determines the operation:

​
type: “sync”

Synchronises the client’s localStorage snapshot with the server.
Request the server’s current snapshot for an origin. Use this when a page first loads.
{
  "type": "sync",
  "fetch": true
}
Response: the server’s stored data and its timestamp. If the server has no record for this origin yet, an empty object is stored and returned.
{
  "timestamp": 1715000000000,
  "data": {
    "key": "value"
  }
}
​
timestamp
number
Unix millisecond timestamp of the stored snapshot.
​
data
object
The full localStorage contents for this origin, as { key: string } pairs.

​
type: “update”

Applies a partial update to the server’s stored snapshot without replacing it. The origin must have been synced at least once before using update. 
{
  "type": "update",
  "updateData": {
    "newKey": "newValue"
  }
}
​
updateData
object
required
A partial localStorage object. Keys are merged into the existing server-side data. All values must be non-empty strings.
Response: 
{ "timestamp": 1715000000123 }
​
timestamp
number
The new server-side timestamp after the update was applied.

​
GET /rammerhead.js

Serves the compiled Rammerhead client-side script. This route is registered automatically by RammerheadProxy — you do not need to configure it. 
curl http://localhost:8080/rammerhead.js
Response: JavaScript (application/x-javascript). In development mode (DEVELOPMENT=1), the unminified build is served; otherwise the minified build is used. Include this script in your proxy UI page to enable client-side URL rewriting: 
<script src="/rammerhead.js"></script>

Build docs developers (and LLMs) love

Get started for freeTalk to us