Recording Proxy

The recording proxy captures HTTP requests and responses flowing through it, then exports them as .http files. It is a fast way to bootstrap tests from existing API traffic.

How It Works

Start the proxy pointing at your target server
Send requests through the proxy (manually or from your app)
Stop the proxy (Ctrl+C)
hitspec exports all captured traffic as a .http file

Quick Start

# Start recording proxy
hitspec record --port 8080 --target https://api.example.com

# In another terminal, send requests through the proxy
curl http://localhost:8080/users
curl -X POST http://localhost:8080/users -d '{"name":"John"}'

# Press Ctrl+C to stop and export

Flags

Flag	Short	Description	Default
`--port`	`-p`	Port to run the proxy on	`8080`
`--target`	`-t`	Target URL to proxy to (required)
`--output`	`-o`	Output file path (default: stdout)
`--exclude`		Paths to exclude (comma-separated)
`--verbose`	`-v`	Enable verbose logging	`false`
`--dedupe`		Skip duplicate requests (same method+path)	`false`
`--json`		Export as JSON instead of `.http` format	`false`

Examples

hitspec record --target https://api.example.com -o recorded.http

hitspec record \
  --target https://api.example.com \
  --exclude "/health,/metrics" \
  -o recorded.http

hitspec record \
  --target https://api.example.com \
  --dedupe \
  -o recorded.http

hitspec record \
  --target https://api.example.com \
  --json \
  -o recorded.json

What Gets Recorded

The proxy captures:

HTTP method and URL
Request headers
Request body
Response status code

What Gets Sanitized

The proxy automatically sanitizes sensitive headers in the output:

Authorization headers are replaced with placeholders
Cookie headers are replaced with placeholders
Other sensitive headers are cleaned

Output Format

The exported .http file follows standard hitspec format:

### GET /users
# @name get_users

GET https://api.example.com/users
Accept: application/json

>>>
expect status == 200
<<<

### POST /users
# @name post_users

POST https://api.example.com/users
Content-Type: application/json

{
  "name": "John"
}

>>>
expect status == 200
<<<

After recording, edit the generated file to add meaningful assertions, replace hardcoded values with variables, and add @depends directives for request ordering.

Last modified on February 10, 2026

Contract Testing Watch Mode

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Recording Proxy

How It Works

Quick Start

Flags

Examples

What Gets Recorded

What Gets Sanitized

Output Format

​How It Works

​Quick Start

​Flags

​Examples

​What Gets Recorded

​What Gets Sanitized

​Output Format

How It Works

Quick Start

Flags

Examples

What Gets Recorded

What Gets Sanitized

Output Format