Module

http.request

http.request(method, url, [options]) -> Response

Creates and sends an HTTP request with the given method, URL, and options.

Options:

Name	Type	Description
headers	dictionary	Headers to be used with the Request.
query	dictionary	Query string parameters to add to the URL.
data	string OR table OR FormData	Data to send in the body of the request. Tables will automatically be encoded as JSON.
cookies	dictionary OR CookieJar	Cookies to send with request.
ignore_ratelimit	bool	If true, the rate-limit will be ignored for this request.

http.get, post, head, put, delete, patch, options

http.get(url, [options]) -> Response

Shortcut methods for http.request.

http.promise_request

http.promise_request(method, url, [opts]) -> Promise

This has the same functionality as http.request but returns a Promise.

http.promise_get, promise_post, promise_…

http.promise_get(url, [opts]) -> Promise

Shortcut methods for http.promise_request

http.set_ratelimit

http.set_ratelimit(requests, period)

Changes global rate limit. Default is 250 requests / 30 seconds.

http.Request

http.Request(method, url, [options]) -> Request

Creates and prepares a Request object.

Attributes

Note: These attributes are all read-only. Use the provided methods instead of setting them directly.

• method (string) - HTTP verb used for request
• url (string) - URL request is sent to
• headers (dictionary) - Headers used for this request
• query (dictionary) - Parameters to add to URL
• data (string) - Raw data sent with request

Request:set_headers

Request:set_headers(headers)

Updates request headers based on a dictionary of new headers.

Request:set_query

Request:set_query(params)

Updates URL query string based on a dictionary of parameters.

Request:set_data

Request:set_data(data)

Sets new data for request. The data can be a string, table (JSON), or FormData.

Request:send

Request:send() -> Response

Sends the request and returns a Response object.

Request:promise

Request:promise() -> Promise

Returns a Promise. The Promise will resolve with the response object if the response has a 2xx status code. Otherwise, the Promise will reject with this rejection table:

Name	Type	Description
request_sent	bool	Whether the request was sent successfully.
response	bool	The response object. This value is only present if request_sent is true.
error	string	The error thrown during preparation of the request if request_sent is false.

Response

Attributes

• request (Request) - Request that generated this response
• url (string) - Requests’ URL
• method (string) - Request’s HTTP method
• ok (bool) - true if response has OK status code (200 <= code < 300)
• status_code (number) - Status code of reponse
• message (string) - Status message of response
• response_time (number) - Time the request took in seconds
• timestamp (number) - Epoch time the request was sent at
• from_cache (bool) - Whether the response was accessed from the cache
• headers (dictionary) - Headers sent in response
• text (string) - Response body
• cookies (CookieJar) - New cookies sent in this response

Response:json

Response:json() -> Variant

Converts JSON response to a Lua object.

http.Session

http.Session([base_url]) -> Session

Creates a session with an optional base URL.

All main module methods also apply to sessions.

Attributes

• headers (dictionary) - Default headers used with each request
• cookies (CookieJar) - Current session cookies. Updates automatically from Set-Cookie header
• base_url (string) - Base URL to prefix each request with. If a request URL contains the HTTP protocol (http(s)://), this will be ignored
• ignore_ratelimit (bool) - If true, all requests will ignore the global rate-limit

Session:set_headers

Session:set_headers(new_headers)

Updates headers dictionary with values of new_headers.

Session:set_ratelimit

Session:set_ratelimit([requests[, seconds]])

Sets custom rate-limit for the Session. Requests sent by the session must follow this ratelimit and the global ratelimit.

If no values are provided, this will disable the session ratelimit. This will not disable the global ratelimit.

This can be changed at any time by calling the function again.

session:request

session:request(method, url, [opts]) -> Response

Creates and sends a request prepared with session defaults. Options specified here will override the session values.

Session:get, post, head, put, delete, patch, options

Session:get(url, [opts]) -> Response

Shortcut methods for session:request

Session:promise_request

Session:promise_request(method, url, [opts]) -> Promise

This has the same functionality as session:request but returns a Promise.

Session:promise_get, promise_post, promise_…

Session:promise_get(url, [opts]) -> Promise

Shortcut methods for Session:promise_request

Session:Request

Session:Request(method, url, [opts]) -> Request

Creates a Request prepared with session defaults. Options specified here will override the session values.

http.cache

http.cache.update_settings

http.cache.update_settings(url, opts)

http.cache.update_settings(urls, opts)

Updates cache settings for one or more URL patterns.

Example patterns:

• "github.com" - Matches all subdirectories for GitHub
• "*.github.com" - Matches all subdomains and subdirectories for GitHub
• "github.com/" - Matches ONLY “http(s)://github.com/”
• "github.com/*/stars" - Matches stars directory for any GitHub user

Options:

Name	Type	Description
cache_locally	Optional[bool]	Whether to cache locally (on this server). Defaults to true
cache_globally	Optional[bool]	Whether to use datastores to cache across servers. Defaults to false
expires	Optional[number]	Max age in seconds of a cached response.

http.cache.cache_locally

http.cache.cache_locally(urls, opts)

Same as update_settings but automatically sets cache_locally to true.

http.cache.cache_globally

http.cache.cache_globally(urls, opts)

Same as update_settings but automatically sets cache_globally to true.

http.FormData

http.FormData(fields) -> FormData

Creates form data based on given fields. Fields should be passed in a dictionary.

FormData:AddField

FormData:AddField(name, value)

Adds field with given name and value.

http.File

http.File(content) -> File

http.File(filename, content, [content_type]) -> File

Creates a file for use in a FormData field. If no content type is specified, it will be guessed from the file extension.

http.CookieJar

CookieJars are used to store and persist cookies. This is the object referenced by session.cookies.

CookieJar:insert

CookieJar:insert(name, value, options)

Creates a new cookie with an optional domain and path

Options:

Name	Type	Description
domain	string	If specified, the cookie will only apply to URLs on this domain.
path	string	If specified, the cookie will only apply to URLs that begin with this path.

CookieJar:delete

CookieJar:delete(name)

Deletes a cookie.