GET retrieves. POST sends data to create or submit something — a new record, a form, a login.

import requests

payload = {"name": "Ada", "role": "engineer"}
response = requests.post("https://api.example.com/users", json=payload)

print(response.status_code)
print(response.json())

A successful POST usually returns 201 Created rather than 200, often with the newly created record in the body.

json= versus data=

This distinction matters:

import requests

requests.post(url, json={"name": "Ada"})

requests.post(url, data={"name": "Ada"})

• json= serialises the dictionary to JSON and sets Content-Type: application/json. This is what modern APIs expect.
• data= sends it as form-encoded (name=Ada), like an HTML form submission. Older APIs and login forms often want this.

Reach for json= unless the documentation says otherwise.

The other methods

| Method | Purpose | Typical success | | --- | --- | --- | | GET | read | 200 | | POST | create | 201 | | PUT | replace an entire record | 200 | | PATCH | update some fields | 200 | | DELETE | remove | 204 (no content) |

import requests

requests.put(f"{url}/1", json={"name": "Ada", "role": "lead"})
requests.patch(f"{url}/1", json={"role": "lead"})
requests.delete(f"{url}/1")

PUT replaces the whole thing — omit a field and it's usually cleared. PATCH changes only what you send.

Safe versus unsafe

GET is safe: it shouldn't change anything, so retrying is harmless. POST is not — if a request times out, you genuinely don't know whether the server processed it. Retrying could create a duplicate.

That's why you should never hide a state-changing operation behind GET, and why retry logic needs more care for POST than for GET.

Sending headers with a POST

Same as lesson 8.3 — combine authentication with the payload:

import requests
import os

headers = {"Authorization": f"Bearer {os.environ.get('API_TOKEN', '')}"}
payload = {"title": "New post", "body": "Hello"}

response = requests.post(
    "https://api.example.com/posts",
    json=payload,
    headers=headers,
    timeout=10,
)

timeout=10 is covered next lesson, but get in the habit now.

Try it yourself

A fake endpoint that validates a payload and returns realistic status codes.

Checkpoint

• requests.post(url, json=payload) sends data; 201 usually means created.
• json= sends JSON, data= sends form encoding — prefer json= for modern APIs.
• PUT replaces, PATCH updates fields, DELETE removes.
• GET is safe to retry; POST is not — a timeout leaves the outcome genuinely unknown.