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	Type	Description
`Url`	`string`	Required HTTP or HTTPS URL.
`Method`	`string?`	Defaults to GET. Accepted methods are GET, HEAD, POST, PUT, DELETE, OPTIONS, and PATCH; case is normalized.
`Body`	`string?`	Optional body string. Serialize tables before assigning this field.
`Headers`	`{[string]: string}?`	Optional map of HTTP header names to string values. A custom User-Agent is preserved; otherwise Kawaii supplies its default. Header-name casing does not change that rule.
`Cookies`	`{[string]: string}?`	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	Type	Description
`Success`	`boolean`	Whether the returned HTTP status indicates success.
`Body`	`string`	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`	`number`	Numeric HTTP response status.
`StatusMessage`	`string`	Text describing the response status.
`Headers`	`{[string]: string}`	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.

A User-Agent supplied in Headers is preserved, regardless of header-name casing. When omitted, Kawaii supplies its default. Kawaii still generates its own fingerprint 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	No fixed Kawaii limit	The complete body is buffered before the call returns, so available memory and the deadlines below still apply. A failed read raises an error rather than returning a truncated body.
Content encoding	No fixed layer count or decoding budget	gzip, deflate, and identity are supported. An unsupported or malformed encoding raises an error.
Active requests	64 across the process	Another request raises an error until one of them finishes. HTTP calls from every script share this count.
Redirects	10 per request	One more redirect raises an error.
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. A large or highly compressed response can use substantial memory and processor time, so request only what your script is prepared to hold. 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",
    Headers = { ["User-Agent"] = "MyTool/1.0" },
})
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