title: Overview description: The capture script model: rule configuration, execution order, $request / $response / $done, $argument, and console.

HTTP capture scripts let you rewrite matching requests and responses with JavaScript while capturing traffic. A script is attached to a capture rule and runs inside the capture engine when the rule's pattern matches a request URL.

These APIs ($request, $response, $done, $argument, console, $httpClient, $persistentStore, $notification, $utils) are available only inside capture rule scripts — not in regular scripts, and they are not imported.

#Rule configuration

Each rule is configured in the rule editor:

#Execution model

When several rules match the same message, they run in the order they appear in the list, and the effects accumulate: each script sees the output of the previous one. A request script that returns a mock response (see below) short-circuits the chain — no upstream request is made and no response scripts run.

If a script throws, times out, or never calls $done(...), the message passes through unchanged. Scripts can never break traffic they don't intend to.

#$request

Available in both request and response scripts.

$request: {
  url: string
  method: string
  headers: Record<string, string>
  body?: string | Uint8Array   // present only when Requires Body is on
}

In a response script, $request is read-only and exposes url and method for context.

#$response

Available in response scripts.

$response: {
  status: number
  headers: Record<string, string>
  body?: string | Uint8Array   // present only when Requires Body is on
}

The body is already decompressed: if the response used Content-Encoding such as gzip, body is the decoded content. Use $utils.ungzip only for data that is gzip-compressed at the application layer.

#$done

Every script must call $done(...) exactly once to finish. The shape of the argument determines the outcome.

#Request scripts

// Pass through unchanged
$done({})

// Rewrite the outgoing request (any field may be omitted)
$done({
  url?: string,
  headers?: Record<string, string>,
  body?: string | Uint8Array,
})

// Return a mock response without contacting the server (short-circuits the chain)
$done({
  response: {
    status: number,
    headers?: Record<string, string>,
    body?: string | Uint8Array,
  }
})

#Response scripts

// Pass through unchanged
$done({})

// Rewrite the response (any field may be omitted)
$done({
  status?: number,
  headers?: Record<string, string>,
  body?: string | Uint8Array,
})

When you return headers, they replace the header set that is forwarded. Omit headers to keep the original ones.

#$argument

The value configured on the rule. For a plain argument it is a string; for a structured argument (input / select / switch fields) it is an object keyed by field name.

// Rule argument: token=abc123
const token = $argument            // "abc123"

// Structured argument
const enabled = $argument.enabled  // true

#console

console.log(...args: any[]): void

console.log writes to the capture log for debugging.

#Example

// Request script: inject a header and add a query flag.
const headers = $request.headers
headers["X-Debug"] = "1"
$done({ url: $request.url + "?trace=1", headers })

// Response script (Requires Body on): add a field to a JSON response.
try {
  const json = JSON.parse($response.body)
  json.injected = true
  $done({ body: JSON.stringify(json) })
} catch (e) {
  $done({})
}

#Related APIs

• $httpClient — send HTTP requests from a script.
• $persistentStore — read and write persistent values.
• $notification — post a local notification.
• $utils — utility helpers (ungzip, …).