How to Send a POST Request With cURL?
Sending a POST request with cURL is a common task in web development and API interactions. When making a POST request, cURL allows you to send data to a server, often to submit forms or interact with APIs. Understanding how to craft and send POST requests using cURL is essential for testing APIs, debugging, and automating web interactions. In this guide, we'll explore how to use cURL to send POST requests effectively.
What is a POST request in cURL?
A cURL POST request offers a method for communicating with web servers and APIs right from the Command line or within a script, enabling the transmission of data to either create or modify resources. This type of request is structured around several key components:
- URL. Specifies the endpoint to which the request is sent. This is the target resource or API where the data will be processed, provided directly after the cURL command and options.
- Headers. Included using the -H or --header flag followed by the header name and value. Headers in a cURL POST request can include content type (e.g., -H "Content-Type: application/json" for JSON payloads), authentication (e.g., -H "Authorization: Bearer TOKEN"), and any other necessary metadata required by the server or API.
- Body. The data payload of the POST request added using the -d or --data flag. This can be a string of key-value pairs for form data, a JSON string, or even a reference to a file containing the payload (using @filename syntax).
Building a cURL POST request with these components gives developers precise control over the data they send to servers, positioning cURL as an instrument for testing, automation, and engagement with web services.
cURL POST request: a step-by-step guide
cURL is a versatile command line tool widely used for interacting with servers, particularly for sending and receiving data across different protocols. Whether you're working with APIs, automating scripts, or troubleshooting network issues, understanding how to send POST requests with cURL is essential. This guide will take you through each step, from sending your first POST request to more advanced options. For those who need to work with proxies for added security or anonymity, be sure to check out our comprehensive cURL with proxies guide.
How to send a basic POST request?
To send a basic POST request with cURL, use the -X POST option followed by the URL you're targeting:
curl -X POST http://example.com/api/resource
POST request options (arguments)
This table covers the fundamental arguments for constructing and sending POST requests with cURL, enabling a wide range of HTTP interactions from simple data submissions to complex file uploads and authentication handling:
Short Flag
Equivalent Long Flag
Argument Type
Description
Example Usage
-X
--request
<method>
Specifies the HTTP method for the request. Primarily used to override or specify the method.
-X POST
-d
--data
<data>
Attaches data to the body of the POST request. It can be used multiple times for multiple data pieces.
-d "username=user" -d "password=pass"
-H
--header
<header>/@file
Adds a header to the request. It can also load headers from a file.
-H "Content-Type: application/json"
-F
--form
<name=content>
Used for sending multipart/form-data content. Suitable for text and file uploads.
-F "file=@path/to/file"
-b
--cookie
<data> or <filename>
Sends cookies with the request, specified directly or via a file.
-b "session=abc123" or -b cookies.txt
-c
--cookie-jar
<filename>
Designates a file to save cookies to after the request is complete. Useful for sessions.
-c cookies.txt
-f
--fail
None
Instructs cURL to provide no output and exit early on server errors. Useful for scripts.
-f
-b
--cookie
<data> or <filename>
Sends cookies with the request, specified directly or via a file.
-b "session=abc123" or -b cookies.txt
-c
--cookie-jar
<filename>
Designates a file to save cookies to after the request is complete. Useful for sessions.
-c cookies.txt
-f
--fail
None
Instructs cURL to provide no output and exit early on server errors. Useful for scripts.
-f
-i
--include
None
Includes the HTTP headers in the output. Useful for debugging or when headers are needed.
-i
-k
--insecure
None
Allows connections to SSL sites without certificates or with incorrect certificates.
-k
-L
--location
None
Follows HTTP redirects, redoing the request on the new location. Essential for some APIs.
-L
-o
--output
<file>
Writes the output to a file instead of stdout. Useful for downloading files.
-o output.html
-s
--silent
None
Operates in silent mode, not showing progress or error messages. Ideal for automation.
-s
-v
--verbose
None
Provides detailed operation information, useful for troubleshooting.
-v
-w
--write-out
<format>
Displays information on stdout after a completed transfer, formatted as specified.
-w "%{http_code}"
#1 Table. cURL POST request options (arguments)
What is Request-Response cycle?
Here's a diagram illustrating the step-by-step process of sending a POST request with cURL and receiving a response from the server. This diagram includes decision points for handling different HTTP status codes, error handling, and retries.
#2 Diagram. cURL POST Request-Response cycle. View full
How to send data with a POST method?
To send data with your POST request, use the -d (or --data) option. This data is typically presented in the form of key-value pairs:
curl -X POST -d "key1=value1&key2=value2" http://example.com/api/resource
Remember, when adding data to your POST request, it's crucial to correctly specify the Content-Type header to match the type of data you're transmitting. If not, the server might struggle to process your request correctly. We'll dive into this in the sections below.
How to send JSON data?
When sending JSON data with cURL, it's important to set the Content-Type header to application/json to inform the server about the type of data being sent. This is done using the -H (or --header) option. The data itself is passed with the -d (or --data) option, formatted as a JSON string. Here's an example:
curl -X POST -H "Content-Type: application/json" -d '{"key": "value", "number": 123, "boolean": true}' http://example.com/api/endpoint
- -X POST specifies the request method.
- -H "Content-Type: application/json" sets the header to indicate the resource's media type.
- -d '{"key": "value", "number": 123, "boolean": true}' provides the JSON data to be sent to the server. This JSON string includes various data types commonly used in JSON, such as strings ("key": "value"), numbers ("number": 123), and booleans ("boolean": true).
How to post XML data?
When posting XML data with cURL, you should set the Content-Type header to application/xml or text/xml, depending on the requirements of the server you're interacting with. This header is set using the -H flag, and the XML data itself is included with the -d option. Here’s how you can send a POST request with XML data:
curl -X POST -H "Content-Type: application/xml" -d '<person><name>John Smith</name><age>30</age></person>' http://example.com/api/endpoint
- -X POST specifies that the HTTP method is POST.
- -H "Content-Type: application/xml" sets the request header to inform the server that the data being sent is in XML format.
- -d '<person><name>John Smith</name><age>30</age></person>' is the XML data payload. This example represents a simple XML document with a person element containing name and age elements.
How to send form data?
Form data is a common method of data transmission in web interactions, especially in HTTP POST requests. It's the standard approach for submitting web forms, accommodating diverse fields like text entries, choices, and file uploads. When utilizing cURL to dispatch form data, shaping the request to replicate a web browser's form submission process is key.
How to set MIME types for form data?
When submitting form data, the MIME type (media type or content type) used is application/x-www-form-urlencoded for standard text inputs. For more complex forms, particularly those involving file uploads, the MIME type should be multipart/form-data. Note that cURL automatically uses multipart/form-data when the -F flag is used.
How to send standard form fields?
To send standard text fields (like username and password inputs), you can use the -F (or --form) flag with cURL, which automatically sets the content type to multipart/form-data. Here's an example of submitting simple form fields:
curl -X POST -F "username=johndoe" -F "password=123456" http://example.com/api/login
- -F "username=johndoe" and -F "password=123456" represent the form data being sent.
- Each -F adds another key-value pair to the request, mimicking the form fields in a web form.
- Checkboxes and selections. For a form with checkboxes or selection dropdowns, use the -F flag for each option. If a checkbox is checked, include it with its value; otherwise, omit it.
How to submit advanced forms?
Forms often contain more than simple text inputs; they may include selections, checkboxes, and file uploads. Here’s how to handle various form elements with cURL:
How to use encoding and special characters?
When sending form data, ensure that special characters are properly encoded, especially in URLs and form field values. cURL handles some of this encoding automatically when using the -F flag. However, when manually crafting data with the -d flag and using application/x-www-form-urlencoded, pay special attention to characters that may require percent-encoding.
How to debug form data requests?
Debugging form data submissions with cURL can be facilitated using the -v (verbose) flag to view the request headers and body. This can help ensure that your form data is being sent as expected. We’ll cover the verbose mode in detail in the dedicated section below.
Conclusion
Mastering cURL for sending POST requests is essential for anyone involved in web development or API integration. With the steps outlined in this guide, you should now be able to install cURL, send POST requests, and even use proxies for enhanced security. Whether you're testing APIs or automating tasks, cURL provides a powerful, flexible tool to do the job efficiently.
Looking for other relevant guides on cURL? We would recommend checking our other articles on this topic:
To find answers to other questions you may have, check out the official documentation for cURL.
About the author
Martin Ganchev
VP Enterprise Partnerships
Martin, aka the driving force behind our business expansion, is extremely passionate about exploring fresh opportunities, fostering lasting relationships in the proxy market, and, of course, sharing his insights with you.
All information on Smartproxy Blog is provided on an "as is" basis and for informational purposes only. We make no representation and disclaim all liability with respect to your use of any information contained on Smartproxy Blog or any third-party websites that may be linked therein.