API Reference

Create a new proxy session. Returns the port number of the new proxy listener. Optionally request a specific port.

Request Parameters (form-encoded or query)

Parameter	Type	Description
port	integer	Optional. Request a specific port for the proxy listener.
trustAllServers	boolean	Optional. Skip upstream TLS certificate verification.

Response

{
  "port": 8081
}

Example

# Create proxy on auto-assigned port
curl -X POST http://localhost:8080/proxy

# Create proxy on specific port
curl -X POST http://localhost:8080/proxy?port=9091

List all active proxy sessions and their ports.

Response

{
  "proxyList": [
    { "port": 8081 },
    { "port": 8082 }
  ]
}

Example

curl http://localhost:8080/proxy

Shut down a proxy session and release its port. Any in-progress HAR data is discarded.

Path Parameters

Parameter	Type	Description
port	integer	The port of the proxy session to delete.

Example

curl -X DELETE http://localhost:8080/proxy/8081

Start or reset HAR capture for the given proxy session. If HAR capture is already active, this resets and returns the previous HAR data.

Request Parameters (form-encoded or query)

Parameter	Type	Description
initialPageRef	string	Optional. Name of the initial page ref. Defaults to "Page 1".
initialPageTitle	string	Optional. Title of the initial page.
captureHeaders	boolean	Optional. Capture request/response headers. Default: false.
captureContent	boolean	Optional. Capture response body content. Default: false.
captureBinaryContent	boolean	Optional. Capture binary response bodies as base64. Default: false.

Response

Returns the previous HAR data if capture was already active, otherwise empty.

Example

# Start HAR capture with headers and content
curl -X PUT "http://localhost:8080/proxy/8081/har?captureHeaders=true&captureContent=true"

Retrieve the current HAR data for the proxy session. Returns a complete HAR 1.2 JSON document.

Response

{
  "log": {
    "version": "1.2",
    "creator": { "name": "har-capture-proxy", "version": "0.1.0" },
    "pages": [...],
    "entries": [...]
  }
}

Example

# Retrieve HAR and save to file
curl http://localhost:8080/proxy/8081/har -o capture.har

Start a new page within the current HAR capture. Subsequent entries are associated with the new page ref.

Request Parameters (form-encoded or query)

Parameter	Type	Description
pageRef	string	Name of the new page ref.
pageTitle	string	Optional. Title of the new page.

Example

curl -X PUT "http://localhost:8080/proxy/8081/har/pageRef?pageRef=checkout&pageTitle=Checkout+Page"

Set additional headers that will be sent with every request through this proxy session.

Request Body (JSON)

{
  "X-Custom-Header": "my-value",
  "Authorization": "Bearer token123"
}

Example

curl -X POST http://localhost:8080/proxy/8081/headers \
  -H "Content-Type: application/json" \
  -d '{"X-Custom-Header": "my-value"}'

Set basic authentication credentials for a specific domain. The proxy will automatically add the Authorization header for matching requests.

Path Parameters

Parameter	Type	Description
domain	string	The domain to authenticate to (e.g., "example.com").

Request Body (JSON)

{
  "username": "admin",
  "password": "secret"
}

Example

curl -X POST http://localhost:8080/proxy/8081/auth/basic/example.com \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "secret"}'

Set a whitelist of URL patterns. Requests not matching any pattern receive the specified HTTP status code.

Request Parameters (form-encoded)

Parameter	Type	Description
regex	string	Comma-separated list of regex patterns to whitelist.
status	integer	HTTP status code to return for non-matching requests (e.g., 404).

Example

curl -X PUT http://localhost:8080/proxy/8081/whitelist \
  -d "regex=.*\.example\.com.*,.*\.cdn\.com.*&status=404"

Clear the whitelist, allowing all requests through.

Example

curl -X DELETE http://localhost:8080/proxy/8081/whitelist

Add a URL pattern to the blacklist. Matching requests receive the specified HTTP status code.

Request Parameters (form-encoded)

Parameter	Type	Description
regex	string	Regex pattern to blacklist.
status	integer	HTTP status code to return for matching requests (e.g., 403).

Example

curl -X PUT http://localhost:8080/proxy/8081/blacklist \
  -d "regex=.*\.tracking\.com.*&status=403"

Set bandwidth limits and latency for the proxy session. Useful for simulating slow network conditions.

Request Parameters (form-encoded)

Parameter	Type	Description
downstreamKbps	integer	Downstream bandwidth limit in Kbps.
upstreamKbps	integer	Upstream bandwidth limit in Kbps.
latency	integer	Added latency in milliseconds.
enable	boolean	Enable or disable bandwidth limiting. Default: true.
payloadPercentage	integer	Percentage of data to consider as payload. Default: 100.
maxBitsPerSecond	integer	Alternative: max bits per second (downstream).

Example

# Simulate 3G network
curl -X PUT http://localhost:8080/proxy/8081/limit \
  -d "downstreamKbps=384&upstreamKbps=128&latency=200"

Set connection and request timeouts for the proxy session.

Request Parameters (form-encoded or JSON)

Parameter	Type	Description
requestTimeout	integer	Request timeout in milliseconds.
readTimeout	integer	Read timeout in milliseconds.
connectionTimeout	integer	Connection timeout in milliseconds.
dnsCacheTimeout	integer	DNS cache TTL in seconds.

Example

curl -X PUT http://localhost:8080/proxy/8081/timeout \
  -d "requestTimeout=30000&connectionTimeout=5000"

Map hostnames to IP addresses, overriding DNS resolution for the proxy session.

Request Body (JSON)

{
  "example.com": "127.0.0.1",
  "api.example.com": "10.0.0.5"
}

Example

curl -X POST http://localhost:8080/proxy/8081/hosts \
  -H "Content-Type: application/json" \
  -d '{"example.com": "127.0.0.1"}'

Set the number of retry attempts for failed requests.

Request Parameters (form-encoded)

Parameter	Type	Description
retrycount	integer	Number of retry attempts. 0 disables retries.

Example

curl -X PUT http://localhost:8080/proxy/8081/retry \
  -d "retrycount=3"

Add URL rewrite rules. Matching URLs are rewritten before the request is forwarded upstream.

Request Body (JSON)

{
  "matchRegex": "http://example\\.com/(.*)",
  "replace": "http://staging.example.com/$1"
}

Example

curl -X PUT http://localhost:8080/proxy/8081/rewrite \
  -H "Content-Type: application/json" \
  -d '{"matchRegex": "http://example\\.com/(.*)", "replace": "http://staging.example.com/$1"}'

Clear the DNS cache for the proxy session.

Example

curl -X DELETE http://localhost:8080/proxy/8081/dns/cache

Wait for all active requests to complete, up to the specified timeout. Useful for ensuring all traffic is captured before retrieving HAR.

Request Parameters (form-encoded)

Parameter	Type	Description
quietPeriodInMs	integer	Wait until no new requests have been made for this many milliseconds.
timeoutInMs	integer	Maximum time to wait in milliseconds.

Example

curl -X PUT "http://localhost:8080/proxy/8081/wait?quietPeriodInMs=2000&timeoutInMs=30000"

Add a JavaScript request filter. The script receives the request object and can modify headers, URL, or body before it is forwarded upstream.

Request Body (text/plain)

A JavaScript function body that receives request and contents parameters.

Example

curl -X POST http://localhost:8080/proxy/8081/filter/request \
  -H "Content-Type: text/plain" \
  -d 'request.headers().add("X-Test", "true");'

Add a JavaScript response filter. The script receives the response object and can modify headers, status, or body before it is returned to the client.

Request Body (text/plain)

A JavaScript function body that receives response and contents parameters.

Example

curl -X POST http://localhost:8080/proxy/8081/filter/response \
  -H "Content-Type: text/plain" \
  -d 'response.headers().add("X-Proxied", "har-capture-proxy");'

Add one or more response mutation rules. Rules are matched against responses by URL pattern and applied in order. Supports JSON mutations (JSONPath), HTML transforms (CSS selectors), text replacements, and sandboxed JavaScript transforms.

Request Body (JSON)

An array of rule objects. Each rule has a url_pattern (regex) and one or more mutation types.

JSON Mutation Rule

[
  {
    "url_pattern": ".*api\\.example\\.com/users.*",
    "json_mutations": [
      {
        "selector": "$.data[*].email",
        "action": "set",
        "value": "redacted@example.com"
      },
      {
        "selector": "$.data[*].phone",
        "action": "delete"
      }
    ]
  }
]

HTML Transform Rule

[
  {
    "url_pattern": ".*example\\.com.*",
    "html_transforms": [
      {
        "selector": "h1.title",
        "action": "set_text",
        "value": "Modified Title"
      },
      {
        "selector": "img.logo",
        "action": "set_attribute",
        "attribute": "src",
        "value": "/custom-logo.png"
      }
    ]
  }
]

Text Replacement Rule

[
  {
    "url_pattern": ".*example\\.com.*",
    "text_replacements": [
      {
        "find": "Old Company Name",
        "replace": "New Company Name"
      }
    ]
  }
]

JavaScript Transform Rule

[
  {
    "url_pattern": ".*api\\.example\\.com/data.*",
    "js_transform": "function transform(body) { let data = JSON.parse(body); data.timestamp = Date.now(); return JSON.stringify(data); }"
  }
]

Fake Data Generation Rule

[
  {
    "url_pattern": ".*api\\.example\\.com/users.*",
    "json_mutations": [
      {
        "selector": "$.data[*].name",
        "action": "set",
        "value": "{{fake.name}}"
      },
      {
        "selector": "$.data[*].email",
        "action": "set",
        "value": "{{fake.email}}"
      }
    ]
  }
]

curl Examples

# Add a JSON mutation rule
curl -X POST http://localhost:8080/proxy/8081/rules \
  -H "Content-Type: application/json" \
  -d '[{"url_pattern": ".*api\\.example\\.com.*", "json_mutations": [{"selector": "$.name", "action": "set", "value": "Test User"}]}]'

# Add an HTML transform rule
curl -X POST http://localhost:8080/proxy/8081/rules \
  -H "Content-Type: application/json" \
  -d '[{"url_pattern": ".*example\\.com.*", "html_transforms": [{"selector": "title", "action": "set_text", "value": "Custom Title"}]}]'

# Add a text replacement rule
curl -X POST http://localhost:8080/proxy/8081/rules \
  -H "Content-Type: application/json" \
  -d '[{"url_pattern": ".*", "text_replacements": [{"find": "foo", "replace": "bar"}]}]'

Retrieve all currently active response mutation rules for the proxy session.

Response

[
  {
    "url_pattern": ".*api\\.example\\.com.*",
    "json_mutations": [
      {
        "selector": "$.name",
        "action": "set",
        "value": "Test User"
      }
    ]
  }
]

Example

curl http://localhost:8080/proxy/8081/rules

Remove all response mutation rules from the proxy session.

Example

curl -X DELETE http://localhost:8080/proxy/8081/rules