Back to blog

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.

Martin Ganchev

Aug 21, 2024

8 min read

cURL request

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.

Diagram: cURL POST Request-Response cycle

#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.

LinkedIn

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.

Frequently asked questions

What is the difference between POST and GET cURL?

In the context of cURL, a tool for making requests to URLs from the command line or scripts, the difference between POST and GET requests primarily lies in their purpose and how data is sent to the server:

  • GET request. A GET request used to retrieve data from a specified resource. Data is sent as URL parameters. GET requests are idempotent, meaning they can be repeated multiple times without changing the result beyond the initial application state change. In cURL, a GET request is made simply by specifying the URL or explicitly using -X GET. Data sent in a GET request is appended to the URL as query parameters. .
  • POST request. A POST request used to send data to a server to create or update a resource. The data is sent in the request body rather than in the URL. This allows more data to be sent because it’s not limited by the URL length. It's also more secure for sensitive data, as the data doesn’t appear in web server logs or browser history. In cURL, a POST request is made using -X POST and -d to include the data.

In summary, the key difference in cURL between POST and GET requests is how data is sent and the intended use of each request type: GET requests are for retrieving data without side effects, while POST requests are for submitting data to be processed by the server, potentially changing server state or creating new resources.

What are cURL alternatives for POST requests?

Are cURL flags or command line options (arguments) case-sensitive?

How to handle rate limits and retries with cURL?

© 2018-2024 smartproxy.com, All Rights Reserved