request Asynchronous

http.request
http_request
syn.request

Make an HTTP request and inspect the full response, including status, headers, and body. Use this for APIs that need methods other than GET or require request headers.

Syntax

Luau

request(options: HttpRequestOptions) -> HttpResponse

Parameters

Function parameters
Parameter	Type	Description
`options`	`HttpRequestOptions`	Table containing Url and optional Method, Headers, Body, and Cookies.

Argument fields

HttpRequestOptions fields

Luau

HttpRequestOptions = {
  Url: string, Method: string?, Body: string?,
  Headers: {[string]: string}?, Cookies: {[string]: string}?
}

Field	Description
`Url`	Required HTTP or HTTPS URL.
`Method`	Defaults to GET. Accepted methods are GET, HEAD, POST, PUT, DELETE, OPTIONS, and PATCH; case is normalized.
`Body`	Optional body string. Serialize tables before assigning this field.
`Headers`	Optional map of HTTP header names to string values.
`Cookies`	Optional map of cookie names to string values, sent with this request.

Returns

HttpResponse

An HttpResponse record with Success, StatusCode, StatusMessage, Headers, and Body.

HttpResponse fields

Luau

HttpResponse = {
  Success: boolean, Body: string, StatusCode: number,
  StatusMessage: string, Headers: {[string]: string}
}

Field	Description
`Success`	Whether the returned HTTP status indicates success.
`Body`	Complete response contents as a string, after supported HTTP content decoding. JSON parsing remains the caller’s responsibility. Oversized or invalid encoded responses raise instead of returning partial contents.
`StatusCode`	Numeric HTTP response status.
`StatusMessage`	Text describing the response status.
`Headers`	Map of response header names to values. There is no separate Cookies field.

Usage notes

Method defaults to GET in Kawaii. Set Body to a string; JSON payloads need json.encode and a matching Content-Type header.

HTTP error statuses return a response with Success=false. Transport, decode, and resource-limit failures raise an error instead, so use pcall if the request is optional.

Limits

Resource	Limit	What happens
Response body	8 MiB of wire data and 8 MiB at each decoding stage	The call raises an error when any stage exceeds the limit. It does not return a truncated body.
Content encoding	Up to 3 encoding layers; 16 MiB of cumulative decoded output	gzip, deflate, and identity are supported. Unsupported encodings or an exhausted decoding budget raise an error.
Concurrent response readers	4 across the process	An additional response read fails immediately while all readers are busy. This is not a four-request limit.
Transport deadlines	30 seconds to connect, 60 seconds for a read, 90 seconds total	A timeout raises an error. A per-request Timeout option is not supported.

Catch transport and decoding errors with pcall. These limits cover response data held by the transport, not the total memory used by your script. A successful response must still be checked for the HTTP status you expected.

Differences from sUNC

Kawaii defaults Method to GET when it is omitted or nil. The sUNC request type declares Method as required. Explicit method names are normalized to uppercase.

Example

Luau

local ok, response = pcall(request, {
    Url = "https://example.com/",
    Method = "GET",
})
if not ok then
    warn("Could not reach server:", response)
elseif response.Success then
    print(response.StatusCode, response.Body)
else
    warn(response.StatusCode, response.StatusMessage)
end