cURL Builder preview

cURL Builder

Build cURL commands visually without memorizing syntax. Set method, URL, headers, body, and authentication options, then copy the generated command.

Key features

  • GET, POST, PUT, PATCH and DELETE methods
  • Visual header and body builder
  • Bearer and Basic authentication
  • Copy-ready cURL output

Guide

cURL (Client URL) is a command-line tool for transferring data using network protocols. It supports HTTP, HTTPS, FTP, and dozens of other protocols, but its primary use in modern development is making HTTP requests to APIs. Every web developer, backend engineer, and DevOps professional uses cURL regularly for testing endpoints, debugging API issues, and automating data transfers. This guide covers HTTP request construction, authentication methods, header management, data formatting, and practical patterns for API testing.

A basic cURL command has the form: curl https://api.example.com/users. This sends a GET request to the specified URL and prints the response body to the terminal. By default, cURL uses GET, follows no redirects, sends no request body, and shows only the response body (not headers). Every other option builds on this foundation by modifying the method, adding headers, including a body, changing redirect behavior, or adjusting output format. Understanding this default behavior is essential because many debugging sessions start with figuring out which default you need to override.

The -X flag (or --request) sets the HTTP method. curl -X POST https://api.example.com/users sends a POST request. curl -X PUT sends PUT. curl -X DELETE sends DELETE. curl -X PATCH sends PATCH. For GET requests, -X GET is optional because GET is the default. For HEAD requests, use -I (or --head) instead of -X HEAD, as -I also tells cURL to display the response headers. Some developers always include -X for clarity even with GET, which is fine. Using the long form (--request POST) makes scripts more readable.

Request headers are set with the -H flag (or --header). Each header gets its own -H flag. curl -H "Content-Type: application/json" -H "Accept: application/json" sends two headers. Headers that cURL sets by default include Host (derived from the URL), User-Agent (curl/version), and Accept (*/*). Setting a header with -H overrides the default if the header name matches. To remove a default header, set it to an empty value: -H "User-Agent:" sends a request with no User-Agent header. This is useful for testing how servers handle missing headers.

Sending JSON data is the most common POST/PUT/PATCH pattern. Use -d (or --data) for the request body and -H to set the content type: curl -X POST -H "Content-Type: application/json" -d '{"name":"John","email":"john@example.com"}' https://api.example.com/users. The -d flag also implicitly sets the method to POST, so -X POST is technically redundant when -d is present, but including it improves readability. On Windows command prompt, JSON must use double quotes for outer quoting and escaped double quotes inside. The WebRecast builder writes bash-style quoting, so on Windows run its output in Git Bash or WSL, or rewrite the quotes for cmd.

Form data uses a different content type. curl -X POST -d 'username=john&password=secret' https://api.example.com/login sends application/x-www-form-urlencoded data (cURL sets this content type automatically when using -d without specifying Content-Type). For multipart form data (file uploads), use -F (or --form): curl -X POST -F 'file=@photo.jpg' -F 'description=Profile photo' https://api.example.com/upload. The @ symbol before a filename tells cURL to read the file contents. Multiple -F flags send multiple form fields. You can specify the MIME type explicitly: -F 'file=@photo.jpg;type=image/jpeg'.

Authentication methods vary by API. Basic auth uses -u (or --user): curl -u username:password https://api.example.com/data. cURL base64-encodes the credentials and sends them in an Authorization: Basic header. Bearer token auth (used by OAuth 2.0 and JWT-based APIs) uses a header: curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." https://api.example.com/data. API key auth varies by implementation: some APIs accept keys as query parameters (?api_key=xyz), some as headers (-H "X-API-Key: xyz"), and some in the request body. Digest auth uses --digest -u username:password, where cURL handles the challenge-response negotiation automatically.

OAuth 2.0 token acquisition is a common multi-step cURL workflow. First, request a token from the authorization server: curl -X POST -d 'grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET' https://auth.example.com/token. Parse the access_token from the JSON response. Then use the token in subsequent requests: curl -H "Authorization: Bearer ACCESS_TOKEN" https://api.example.com/data. For scripting, you can capture the token using jq: TOKEN=$(curl -s -X POST ... | jq -r '.access_token'). This pattern is standard for server-to-server API communication.

Response inspection flags change what cURL displays. -i (or --include) shows response headers followed by the response body. -v (or --verbose) shows the complete request and response including TLS handshake, request headers, response headers, and response body. -s (or --silent) suppresses the progress meter. -o (or --output) saves the response to a file: curl -o response.json https://api.example.com/data. -w (or --write-out) outputs specific information after the request completes: curl -w "%{http_code}" prints just the HTTP status code. The -w flag supports many variables including time_total, time_connect, time_starttransfer, size_download, and content_type.

Following redirects requires the -L flag (or --location). By default, cURL does not follow HTTP 301 or 302 redirects. If the server responds with a redirect, cURL shows the redirect response rather than following it to the final destination. -L tells cURL to follow redirects (up to 50 by default, configurable with --max-redirs). For API testing, you usually do not want to follow redirects because the redirect itself is part of the API behavior you are testing. For downloading files or accessing web pages, -L is usually necessary. Use --max-redirs 5 to prevent infinite redirect loops.

Timeout configuration prevents cURL from hanging indefinitely. --connect-timeout 10 sets a 10-second timeout for establishing the connection. --max-time 30 sets a 30-second timeout for the entire operation including data transfer. For API testing, setting both prevents your terminal from freezing when a server is unresponsive. Default behavior is no timeout, meaning cURL waits indefinitely until the server responds or the connection drops. In scripts, always set timeouts. A monitoring script that hangs because a server is down defeats its own purpose.

SSL/TLS options control certificate verification. By default, cURL verifies the server's SSL certificate against the system certificate store. If the certificate is self-signed or expired, cURL refuses the connection with an error. The -k flag (or --insecure) disables certificate verification, which is useful for testing against development servers with self-signed certificates. Never use -k in production scripts or against production APIs because it makes the connection vulnerable to man-in-the-middle attacks. For custom certificate authorities, use --cacert to specify a CA bundle file: curl --cacert /path/to/ca-bundle.crt https://internal-api.example.com/data. For client certificates (mutual TLS), use --cert and --key to provide the client certificate and private key.

Proxy configuration routes requests through a proxy server. -x (or --proxy) specifies the proxy: curl -x http://proxy.company.com:8080 https://api.example.com/data. For SOCKS proxies: curl -x socks5://proxy:1080 https://api.example.com/data. Environment variables http_proxy and https_proxy configure proxies globally for all cURL requests. Corporate networks often require proxy configuration for external API access. --noproxy specifies hosts that should bypass the proxy: --noproxy "localhost,127.0.0.1,.internal.company.com".

Cookie management is necessary for APIs that use session-based authentication. -b (or --cookie) sends cookies: curl -b "session=abc123" https://api.example.com/data. -c (or --cookie-jar) saves response cookies to a file: curl -c cookies.txt https://api.example.com/login -d 'user=john&pass=secret'. Subsequent requests can use the saved cookies: curl -b cookies.txt https://api.example.com/protected. For API testing that involves login flows, the cookie jar approach simulates a browser session. Combining -b and -c in the same command (-b cookies.txt -c cookies.txt) reads existing cookies and updates the file with new ones from the response.

Data from files simplifies sending large request bodies. Instead of pasting JSON directly in the command, read it from a file: curl -X POST -H "Content-Type: application/json" -d @payload.json https://api.example.com/data. The @ prefix tells cURL to read the file. This is cleaner for large payloads and avoids shell quoting issues. You can also read headers from a file or use stdin for the data: echo '{"key":"value"}' | curl -X POST -H "Content-Type: application/json" -d @- https://api.example.com/data (the @- reads from stdin). For binary data, use --data-binary @file.bin instead of -d, which strips newlines.

HTTP/2 and HTTP/3 support in cURL requires specific flags. --http2 forces HTTP/2. --http3 forces HTTP/3 (QUIC). By default, modern cURL versions negotiate the protocol automatically with the server. Testing with specific HTTP versions can reveal protocol-specific issues. curl --http2 -v https://api.example.com/data shows the HTTP/2 negotiation in the verbose output. HTTP/2 server push, multiplexing, and header compression can affect API behavior and performance.

Common API testing patterns include: health checks (curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health returns just the status code), measuring response time (curl -w "Total: %{time_total}s\ " -s -o /dev/null https://api.example.com/data), downloading files with progress (curl -L -O https://example.com/file.zip), testing CORS headers (curl -I -H "Origin: https://mysite.com" https://api.example.com/data and checking Access-Control-Allow-Origin in the response), and sending batch requests in a loop (for id in 1 2 3; do curl -s https://api.example.com/users/$id; done).

Debugging with cURL goes beyond simple request/response inspection. The --trace flag saves a full hex dump of all data sent and received: curl --trace trace.log https://api.example.com/data. The --trace-ascii flag does the same but in ASCII format. These are invaluable for debugging encoding issues, binary protocol problems, and TLS handshake failures. The -w flag with timing variables (time_namelookup, time_connect, time_appconnect, time_pretransfer, time_starttransfer, time_total) breaks down where time is spent in the request lifecycle, helping diagnose latency issues.

Converting cURL commands to code is a frequent need. A cURL command that works in the terminal needs to become a fetch() call in JavaScript, a requests call in Python, or an HttpClient call in C#. The structure maps directly: the URL becomes the first argument, -X maps to the method option, -H flags map to headers, and -d maps to the body. Tools like curlconverter.com automate this translation for many languages. Understanding the mapping helps you go in both directions: building cURL commands to test what your code should do, then implementing the equivalent in your programming language.

Shell quoting is the most common source of cURL errors. In bash, single quotes preserve literal strings (no variable expansion, no special character interpretation). Double quotes allow variable expansion. JSON bodies contain double quotes, so wrapping them in single quotes is cleanest in bash: -d '{"key":"value"}'. In Windows cmd, there are no single quotes, so you must escape inner double quotes: -d "{\"key\":\"value\"}". In PowerShell, use single quotes for the outer string and escape inner quotes, or use a here-string. The WebRecast cURL builder wraps the URL, each header and the body in single quotes, escapes single quotes inside them, and puts each option on its own line with a trailing backslash. With multipart/form-data selected, it turns each key=value line of the body into its own -F option. That output runs in bash and zsh. For cmd or PowerShell you need to change the quotes and line breaks yourself.

Rate limiting and retry logic in cURL scripts handles API throttling gracefully. When an API returns HTTP 429 (Too Many Requests), the Retry-After header tells you how long to wait. A bash script can check the status code and sleep: status=$(curl -s -o /dev/null -w "%{http_code}" ...); if [ "$status" = "429" ]; then sleep 5; fi. For exponential backoff, double the sleep duration on each retry. The --retry flag tells cURL to retry failed requests automatically: curl --retry 3 --retry-delay 5 --retry-max-time 60 retries up to 3 times with 5-second intervals.

cURL config files simplify complex or frequently used configurations. Create a file (typically ~/.curlrc or a project-specific .curlrc) containing options one per line: --silent, --show-error, --connect-timeout 10, --max-time 30. cURL reads this file automatically. Use -K (or --config) to specify an alternative config file: curl -K api-config.txt https://api.example.com/data. This is useful for project-specific defaults like headers, proxy settings, and timeouts. The config file can contain comments (lines starting with #) for documentation.

Parallel requests with cURL speed up batch operations. cURL 7.66+ supports --parallel (or -Z) for running multiple requests simultaneously: curl -Z https://api.example.com/users/1 https://api.example.com/users/2 https://api.example.com/users/3 fetches all three URLs in parallel. The --parallel-max flag limits concurrency. For older cURL versions, use xargs for parallelism: echo "url1 url2 url3" | xargs -n1 -P3 curl -s. GNU parallel offers even more control: parallel curl -s {} ::: url1 url2 url3.

WebSocket testing with cURL is possible in newer versions (7.86+). curl --include --no-buffer --http1.1 -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: ..." -H "Sec-WebSocket-Version: 13" https://ws.example.com/ initiates a WebSocket handshake. For dedicated WebSocket testing, tools like wscat or websocat are more appropriate, but cURL can verify that the initial HTTP upgrade handshake works correctly.

Graphql APIs use cURL with POST requests and a JSON body containing the query. The body format is: -d '{"query":"{ users { name email } }"}'. For mutations: -d '{"query":"mutation { createUser(name: \"John\") { id } }"}'. Variables are passed separately: -d '{"query":"query($id: ID!) { user(id: $id) { name } }","variables":{"id":"123"}}'. Always set Content-Type to application/json. GraphQL introspection queries (-d '{"query":"{ __schema { types { name } } }"}') help explore an unfamiliar API.

Security considerations when using cURL include never storing credentials in command history (use -u with environment variables: curl -u "$API_USER:$API_PASS" ...), avoiding -k/--insecure in production scripts, verifying that sensitive data is sent over HTTPS (not HTTP), and being cautious with --cert and --key flag values in shared environments. If you must include credentials in scripts, read them from a protected file: curl -u $(cat /path/to/credentials) or use a .netrc file with curl -n.

cURL versus other HTTP clients is worth understanding for context. HTTPie (http and https commands) provides a more user-friendly syntax with automatic JSON formatting and colorized output. Postman and Insomnia offer graphical interfaces for building and saving API requests. wget is similar to cURL but focused on downloading files with recursive capabilities. fetch() in JavaScript and requests in Python are the programming language equivalents. cURL remains the universal standard because it is available on virtually every Unix system, it supports every HTTP feature, and its commands are universally understood in documentation and tutorials.

cURL in CI/CD pipelines serves as a lightweight integration testing tool. A deployment pipeline can include cURL-based health checks: after deploying a new version, run curl -sf --max-time 10 https://app.example.com/health to verify the application responds. The -f flag makes cURL return a non-zero exit code on HTTP errors (4xx and 5xx), which the CI system interprets as a test failure. Combine multiple checks into a smoke test script that verifies the health endpoint, a critical API endpoint, and the main page.

Multipart uploads with cURL handle complex scenarios beyond simple file uploads. You can mix file uploads with form fields, specify custom filenames (-F 'file=@localname.jpg;filename=display-name.jpg'), set per-field content types, and upload multiple files in a single field (-F 'files=@photo1.jpg' -F 'files=@photo2.jpg'). For large file uploads, --limit-rate throttles upload speed to avoid saturating the network connection. The --progress-bar flag (-#) shows a simple progress bar instead of the detailed statistics.

Environment-specific cURL configurations help teams work across development, staging, and production environments. Create separate config files (curl-dev.cfg, curl-staging.cfg, curl-prod.cfg) with environment-specific base URLs, authentication credentials (referencing environment variables), and timeout settings. Reference the appropriate file with -K: curl -K curl-staging.cfg /api/users. This prevents accidentally running test commands against production and standardizes API testing across the team.

Response body processing with cURL often involves piping the output to jq (for JSON), xmllint (for XML), or custom scripts. A common pattern: curl -s https://api.example.com/users | jq '.data[] | {name, email}' extracts and formats specific fields from a JSON array. For XML APIs: curl -s https://api.example.com/feed | xmllint --xpath '//item/title/text()' -. Piping to head, tail, wc, or grep performs basic analysis. For monitoring scripts, combining curl -w with response time measurements and jq with response body validation provides comprehensive API health checks in a few lines of bash.

Documentation and sharing cURL commands is a communication skill. When sharing a cURL command in documentation, Slack, or a bug report, format it for readability by using line continuation (backslash at end of line in bash) to break long commands into multiple lines, one flag per line. This makes the command scannable and each option obvious. Include comments explaining non-obvious choices. Omit sensitive values (replace tokens with TOKEN_HERE, passwords with PASSWORD) and note which values the reader needs to replace.

The cURL builder tool lets you construct requests visually by selecting the method, entering the URL, adding headers as key-value pairs, writing the body in a text area, configuring authentication, and setting options like follow redirects and verbose output. The method list covers GET, POST, PUT, PATCH and DELETE. The body field and a Content-Type choice appear for POST, PUT and PATCH. The command updates as you type, and you copy it with one button. This is faster and less error-prone than writing complex cURL commands from memory, particularly when dealing with multiple headers, authentication tokens, and JSON bodies with nested objects.

Frequently asked questions

What is cURL?

cURL is a command-line tool for transferring data using various protocols. It is commonly used for API testing and debugging.

Can I test APIs with this tool?

This tool generates the cURL command which you can paste into your terminal to test APIs directly.

Related guides

Related WebRecast sections