Create a POST request
Submit form fields or raw request content to an HTTP endpoint.
Requests · Function
requests.post
Sends an HTTP POST request and returns a Response. Supply the body with data or with a JSON-serializable value via json, while other request options are passed as keyword arguments.
- Since
- 2.4.2 for the json parameter
How it works
requests.post creates and sends an HTTP POST request to the supplied URL. The request body can be provided through data or as a JSON-serializable object through json; additional request options are forwarded through keyword arguments, and the call returns a Response.
Syntax
requests.post(url: _t.UriType, data: _t.DataType = None, json: _t.JsonType = None, **kwargs: Unpack[_t.PostKwargs]) → ResponseParameters
| Name | Type | Description |
|---|---|---|
url | _t.UriType | URL for the new Request object. |
data | _t.DataType = None | Optional dictionary, list of tuples, bytes, or file-like object to send in the request body. |
json | _t.JsonType = None | Optional JSON-serializable Python object to send in the request body. |
**kwargs | Unpack[_t.PostKwargs] | Optional arguments accepted by request. |
Returns
Response object
Key points
- The function performs an HTTP POST operation.
- url specifies the destination for the newly created request.
- data can carry form-style values, raw bytes, or a stream-like body.
- json accepts Python data that can be represented as JSON.
- Additional keyword options use the same options supported by the general request function.
Common mistakes
- Do not expect json to determine the body when data or files is also supplied; those arguments take precedence.
- Passing serialized JSON through data does not automatically set the JSON Content-Type header; use json when you want Requests to encode the object and set the appropriate header.
Example: Send JSON with POST
import requests
response = requests.post(
"https://httpbin.org/post",
json={"name": "Ada", "active": True},
)
response.raise_for_status()
print(response.json()["json"])
Sends a JSON-encoded POST body and reads the returned JSON response.
When to use it
Post JSON
Send structured application data without manually serializing it.
Stream request data
Upload a stream or file-like body.
Interview questions
QWhat does requests.post return and what are its main body arguments?
It sends a POST request and returns a requests.Response object. url identifies the destination, while data and json are optional body inputs.
Follow-up: What happens when both json and data are supplied? The documentation says json is ignored when either data or files is passed.
QHow do data and json differ?
data accepts a dictionary, list of tuples, bytes, or file-like object for the request body. json accepts a JSON-serializable Python object and handles JSON encoding.
Follow-up: How would you upload a large body without reading it all into memory? Pass a file-like object as data, which supports streamed uploads.
QWhat role does **kwargs play in requests.post?
Keyword arguments are optional arguments accepted by request. The function returns a Response, whose status, headers, and body can then be inspected.
Follow-up: How should an application handle an unsuccessful HTTP status? Inspect the Response or call raise_for_status() so unsuccessful statuses raise an HTTPError.
Related
requests.requestrequests.getrequests.putrequests.patchrequests.deleterequests.optionsrequests.headrequests.Response