POST

What it does

POST submits data to the server, typically to create a new resource. The request body contains the payload (JSON, form data, etc.). Unlike GET, POST is not safe or idempotent—multiple identical POSTs can create multiple resources.

When to use it

• Creating new resources (users, orders, posts)
• Submitting forms
• File uploads
• Actions that don't map to a specific resource URL

Raw HTTP example

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"name": "Jane", "email": "jane@example.com"}

cURL example

Send a POST request with cURL from the command line:

curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane", "email": "jane@example.com"}'

JavaScript Fetch example

Using the Fetch API in the browser or Node.js:

const response = await fetch("https://api.example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Jane", email: "jane@example.com" })
});
const data = await response.json();

Common status codes for POST

POST typically returns these status codes. Check the response to handle each case:

• 201 Created — Resource created successfully; check Location header for the new URL
• 200 OK — Request succeeded (some APIs use 200 instead of 201)
• 400 Bad Request — Invalid body, missing required fields, or validation failed
• 401 Unauthorized — Missing or invalid authentication
• 500 Server Error — Server-side failure

POST vs PUT

POST creates; PUT replaces. Use POST when the server decides the resource URL (e.g. returns 201 with Location header). Use PUT when the client specifies the full URL of the resource to Create/Replace.

Common mistakes

• Forgetting Content-Type header (use application/json for JSON)
• Using POST for idempotent updates (use PUT or PATCH)
• Sending credentials in the URL instead of the body