Send POST request (http.post)

Declaration

code, res_headers_json, body = http.post(URL [, timeout_secs, headers, data, url_no_escape])

Declaration (named arguments)

Supported since 20250625

code, res_headers_json, body = http.post{
    url = URL;
    timeout = timeout_secs;
    headers = headers;
    params = query_params;

    -- The following body options are mutually exclusive, priority: multipart > data > json > upload_file
    multipart = multipart_form;
    data = body_data;
    json = body_json;
    upload_file = upload_file_path;

    download_file = save_response_body_file_path;
}

Parameters

• URL
  String. Request URL. The function escapes the URL by default; see "url_no_escape" if you don't want this.
• timeout_secs
  Number, optional. Timeout in seconds. Default 10.
• headers
  Table, optional. Request headers in the form { field1 = value1, ... }. Default {}.
• query_params
  Table, optional. Query string parameters in the form { field1 = value1, ... }. Default {}.
• body_data
  String or Table, optional. Request body.
  Since 20250625, if a table is provided, it is encoded as application/x-www-form-urlencoded.
• multipart_form
  Table, optional. Multipart form data to send.
• body_json
  Table, optional. Body encoded as application/json.
• upload_file_path
  String, optional. Send file content directly as body.
• save_response_body_file_path
  String, optional. If provided, the returned body is the saved file path on success.
• url_no_escape
  Boolean, optional. true = do not escape URL. Default false.
  For custom escaping, see the lcurl module easy:escape and easy:unescape.

Returns

• code
  Integer. HTTP status code. -1 on timeout.
• res_headers_json
  String or nil. Response headers in JSON. nil on timeout.
• body
  String or nil. Response body. If saved to file, this is the file path. nil on timeout.

Notes

Send data with HTTP/1.1 POST.
This function may yield; other threads may run before it returns.
For HTTP/1.0 or HTTP/0.9 servers you can use:

body = httpPost(URL, string_body, timeout_secs)

Example

local code, res_headers, body = http.post("https://httpbin.org/post?hello=world&你好=世界", 15, {
    ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)", -- simulate IE8
    ["Cookie"] = "a=1; b=2; c=3"; -- send cookies
}, "data to send")
if code == 200 then -- HTTP_OK
    sys.alert(body)
end

Note: Uses sys.alert

Example (named arguments)

local code, res_headers, body = http.post{
    url = "https://httpbin.org/post";
    timeout = 15;
    headers = {
        ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)";
        ["Cookie"] = "a=1; b=2; c=3";
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
    data = "data to send";
}
if code == 200 then
    sys.alert(body)
end

Note: Uses sys.alert

Example: submit form

local c, h, r = http.post('https://httpbin.org/post', 60, {}, 'name=havonz&qq=1004695100&wechat=havonz')
if (c == 200) then
    sys.alert(r, 0, 'Submitted')
else
    if (c == -1) then
        sys.alert('Request failed, please check network', 0, 'Timeout')
    else
        sys.alert('Error #'..c..'\n'..r, 0, 'HTTP Error')
    end
end

Note: Uses sys.alert