This guide covers how to customize the HTTP requests burl sends.
Use -H or --header to add custom headers. This flag can be used multiple times:
burl https://api.example.com \
-H "Authorization: Bearer token123" \
-H "X-Custom-Header: value" \
-H "Accept: application/json"
# API versioning
burl https://api.example.com -H "API-Version: 2024-01"
# Request tracing
burl https://api.example.com -H "X-Request-ID: bench-001"
# Custom user agent
burl https://api.example.com -H "User-Agent: burl/0.1.0"
Use -b or --body for inline request bodies:
# JSON body
burl https://api.example.com/users -m POST \
-b '{"name":"John","email":"john@example.com"}'
# Form data
burl https://api.example.com/login -m POST \
-b "username=admin&password=secret" \
-T application/x-www-form-urlencoded
Use -B or --body-file to read the body from a file:
# Read JSON from file
burl https://api.example.com/users -m POST \
-B payload.json \
-T application/json
# Read any file
burl https://api.example.com/upload -m POST \
-B data.bin \
-T application/octet-stream
Use -T or --content-type as a shorthand for the Content-Type header:
# JSON
burl https://api.example.com -m POST -b '{}' -T application/json
# Form data
burl https://api.example.com -m POST -b 'key=value' -T application/x-www-form-urlencoded
# XML
burl https://api.example.com -m POST -b '<root/>' -T application/xml
This is equivalent to:
burl https://api.example.com -m POST -b '{}' -H "Content-Type: application/json"
Use -a or --auth to add authentication. burl supports two authentication types:
burl https://api.example.com -a bearer:your-token-here
This adds the header: Authorization: Bearer your-token-here
burl https://api.example.com -a basic:username:password
This adds the header with base64-encoded credentials.
For security, use environment variables for tokens:
# Bearer token from environment
burl https://api.example.com -a bearer:$API_TOKEN
# Basic auth with env vars
burl https://api.example.com -a basic:$API_USER:$API_PASS
Use -k or --insecure to skip TLS certificate verification:
burl https://self-signed.example.com -k
Only use --insecure for testing with self-signed certificates. Never use it in production benchmarks.
Here's a comprehensive example using multiple configuration options:
burl https://api.example.com/v2/orders \
-m POST \
-H "X-API-Version: 2024-01" \
-H "X-Request-ID: bench-$(date +%s)" \
-a bearer:$API_TOKEN \
-b '{"product_id": 123, "quantity": 1}' \
-T application/json \
-c 25 \
-d 60s \
-t 15s \
-w 10
This benchmark: