Skip to content
ProbeDocs

Scripting Overview

Scripting lets you run a small JavaScript function against every request that matches a URL pattern. Use it for the edits you'd otherwise make by hand on every call: stamping a header, stripping a cookie, pointing a call at another URL, or rewriting a response body.

A script rule runs in an external JavaScript runtime, not inside Probe: osascript -l JavaScript (JavaScript for Automation) on macOS, otherwise the first of node, bun or deno found on your PATH. Each run has a 5-second timeout. Your script defines handleRequest(request) and/or handleResponse(request, response) and returns the (possibly modified) object.

Scripting editor with syntax highlighting on a real script rewriting a header

Two phases

Section titled “Two phases”

Each rule has two slots. Tick Apply to Request, Apply to Response, or both.

  • Request script runs before the request leaves Probe. handleRequest(request) receives { url, method, headers, body } (headers is a plain object, body a string or null). The url, headers and body you return are sent upstream; the method can't be changed.
  • Response script runs after the upstream response comes back. handleResponse(request, response) receives the request as above and { statusCode, headers, body }; the statusCode, headers and body you return go to the client.

If the script throws, times out, prints something that isn't the JSON result, or no runtime is installed, the traffic is forwarded unchanged.

Matching

Section titled “Matching”

Each script rule has:

  • A URL pattern: a host (api.example.com) or a host and path, with * as a wildcard (api.example.com/v1/*). A leading http:// or https:// is ignored.
  • A method filter: one method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) or * for any.
  • A request script, a response script, or both.

Only the first enabled rule that matches runs, in list order.

Create a rule

Section titled “Create a rule”
  1. Open the Scripting window from the toolbar.
  2. Click + to add a rule.
  3. Enter a URL pattern and pick the method.
  4. Write the request and/or response script in the editor. New rules start from a handleRequest / handleResponse template.
  5. Save. Adding a rule turns scripting on, and it starts firing on matching traffic.

Toggle a rule off without deleting it using the checkbox in the list. The toolbar icon turns purple while scripting is on. Scripting is off again after Probe restarts — your rules are kept, flip the toggle to re-enable them.

A tiny example

Section titled “A tiny example”

Stamp every outgoing request to your API with a trace ID:

// Request script — match: api.example.com/*
function handleRequest(request) {
  request.headers['X-Trace-Id'] = Date.now() + '-' + Math.random().toString(16).slice(2);
  return request;
}

The header is set before Probe forwards the request. Open the captured request in the Detail panel to confirm X-Trace-Id is now there.

The script editor

Section titled “The script editor”

Both the request and response slots open a JavaScript editor:

  • Syntax highlighting and line numbers for JS, themed to match the rest of the app — the editor swaps to a dark scheme automatically when the app is in dark mode and to a light scheme in light mode.
  • Beautify — a button at the top of the editor reformats the current script with a 2-space indent and consistent spacing. Useful after pasting in a one-liner from a chat message.
  • Autocomplete — type request. or response. and the editor offers the fields of the objects your handler receives. Standard JS keywords (function, return, if, etc.) and the JS built-ins (JSON, Math, Date) appear in the same popup.

Runtime notes

Section titled “Runtime notes”
  • The script runs with the runtime's normal permissions — it is not sandboxed. node, bun and deno (started with --allow-all) can read files and open network connections; JXA on macOS can reach Cocoa. Only run scripts you trust.
  • On Windows you need node, bun or deno on your PATH; without one, every rule forwards traffic unchanged.
  • Each run is a fresh process, so nothing you store in a variable survives to the next request.
  • Probe reads the result from the script's standard output. Don't console.log in a rule on node, bun or deno: the log line lands in the same output and the rule is skipped.
Section titled “Related”