Send a POST Request with curl
Learn three practical curl POST patterns—JSON, form-urlencoded, and file uploads—then validate headers, status codes, response bodies, timeouts, retries, and idempotency against a local placeholder endpoint.
Written byYiyao
Use curl to send a POST request when an endpoint expects data in the request body. Match the content type to the body, inspect the HTTP status and keep error responses available for diagnosis.
Send a JSON body from a file
Create a local payload.json containing this fictional sample:
{"project":"demo","limit":2}
Run the command against the public HTTPBin echo service. Send only the sample data shown here.
curl --fail-with-body --show-error --silent --max-time 20 -H "Content-Type: application/json" --data-binary @payload.json https://httpbin.org/post
The data option selects a POST request. The echo response should show the submitted JSON under its json field. In Windows PowerShell, use curl.exe when curl resolves to a shell alias.
Choose the body format the endpoint expects
| Body type | curl direction | Typical use |
|---|---|---|
| JSON | Content-Type plus --data-binary | Structured request fields |
| Form fields | --data-urlencode | URL-encoded form submission |
| Multipart | --form | A form with file parts |
Use the API's documented field names and authentication method. Setting a JSON header does not convert arbitrary text into valid JSON.
Match the request representation to the endpoint's documented contract. A JSON body, a URL-encoded form and a multipart file upload are different encodings. Keep the Content-Type and body format consistent, and let curl generate the multipart boundary when using its form-upload option.
| Request requirement | curl approach | Detail to verify |
|---|---|---|
| JSON object stored in a file | JSON content type with --data-binary @payload.json | Valid JSON and required field names |
| URL-encoded form value | --data-urlencode | Field name and characters requiring encoding |
| Multipart file upload | --form | Endpoint's field name and intended file |
Review the endpoint's example before selecting an option. Sending JSON-looking text with a form content type can produce a server-side validation error even when the connection succeeds.
Inspect a failed request before retrying
Read the response body and status. Check the endpoint, required fields and authentication first. A timeout can leave the server's outcome uncertain, so confirm the operation's state before repeating a request that creates or changes data.
Capture enough evidence to choose the next action. Keep the HTTP status, response body and request identifier where the server provides one. A validation response calls for checking the submitted fields. An authorization response calls for checking access and credentials. A timeout after submission requires extra care: the server may already have accepted the action.
For a state-changing operation, consult the endpoint's retry guidance before sending the same POST again. Where the API supports idempotency keys, follow its documented key handling. A fictional order-import test should first use a clearly identified test record, confirm the recorded result, then establish how duplicate submissions are handled. This makes the retry decision part of the integration rather than a reaction to an empty terminal response.
Keep secrets outside reusable examples
Use the documented credential mechanism for the real service and keep credentials out of shared command history, screenshots and source control. The echo example uses no credentials and does not call an Arcvenza API.
Example: verify a request definition
First send the two-field sample and inspect the echoed data. Then compare the real API specification with your intended field names, types and limits. Test with a non-production resource before using the request in a recurring workflow.
FAQ
Do I need -X POST as well? The data options already select POST for this example.
What if --fail-with-body is unavailable? Check your curl version and its supported options. That option requires curl 7.76.0 or later.
Reference: curl command manual.
Continue with the right workflow
Download and Validate a File with curl · Website Crawler Tasks in One Console · Explore Crawler Console