HttpService

Show Deprecated
Not Creatable
Service

HttpService allows HTTP requests to be sent from game servers using RequestAsync, GetAsync and PostAsync. This service allows games to be integrated with off-Roblox web services such as analytics, data storage, remote server configuration, error reporting, advanced calculations or real-time communication.

You should only send HTTP requests to trusted third-party platforms to avoid making your experience vulnerable to security risks.

Enabling HTTP Requests

Request-sending functions aren't enabled by default: attempting to use them while disabled will result in the error "Http requests are not enabled. Enable via game settings". To send requests, set HttpEnabled to true through the Game Settings interface in Studio under the Security section, or use the Command Bar for unpublished experiences. This property cannot be interacted with at runtime.


1-- For unpublished games, use this in the Command Bar:
2game:GetService("HttpService").HttpEnabled = true
3

Other Functions

HttpService also houses the JSONEncode and JSONDecode functions, which are useful for communicating with services that use the JSON format. In addition, the GenerateGUID function provides random 128-bit labels, which can be treated as probabilistically unique in a variety of scenarios.

Use in Plugins

HttpService can also be used by Roblox Studio plugins. They may do this to check for updates, send usage data, download content or other business logic. The first time a plugin attempts to do this, the user may be prompted to give the plugin permission to communicate with the particular web address. A user may accept, deny and revoke such permissions at any time through the Plugin Management window.

Plugins may also communicate with other software running on the same computer through the localhost and 127.0.0.1 hosts. By running programs compatible with such plugins, you can extend the functionality of your plugin beyond the normal capabilities of Roblox Studio, such as interacting with your computer's file system. Beware that such software must be distributed separately from the plugin itself, and can pose security hazards if you aren't careful.

Considerations

  • There are port restrictions. You cannot use port 1194 or any port below 1024, except 80 and 443. If you try to use a blocked port, you will receive either a 403 Forbidden or ERR_ACCESS_DENIED error.
  • For each Roblox game server, there is a limit of 500 HTTP requests per minute. Exceeding this may cause request-sending functions to stall entirely for about 30 seconds.
  • Requests cannot be made to any Roblox website, such as www.roblox.com.
  • Web requests can fail for many reasons, so it is important to "code defensively" (use pcall) and have a plan for when requests fail.
  • Although the http:// protocol is supported, you should use https:// wherever possible.
  • Requests sent should provide a secure form of authentication, such as a pre-shared secret key, so that bad actors cannot pose as one of your Roblox game servers.
  • Be aware of the general capacity and rate-limiting policies of the web servers to which requests are being sent.

Code Samples

Where is the International Space Station?

1local HttpService = game:GetService("HttpService")
2
3-- Where is the International Space Station right now?
4local URL_ISS = "http://api.open-notify.org/iss-now.json"
5
6local function printISS()
7 local response
8 local data
9 -- Use pcall in case something goes wrong
10 pcall(function()
11 response = HttpService:GetAsync(URL_ISS)
12 data = HttpService:JSONDecode(response)
13 end)
14 -- Did our request fail or our JSON fail to parse?
15 if not data then
16 return false
17 end
18
19 -- Fully check our data for validity. This is dependent on what endpoint you're
20 -- to which you're sending your requests. For this example, this endpoint is
21 -- described here: http://open-notify.org/Open-Notify-API/ISS-Location-Now/
22 if data.message == "success" and data.iss_position then
23 if data.iss_position.latitude and data.iss_position.longitude then
24 print("The International Space Station is currently at:")
25 print(data.iss_position.latitude .. ", " .. data.iss_position.longitude)
26 return true
27 end
28 end
29 return false
30end
31
32if printISS() then
33 print("Success")
34else
35 print("Something went wrong")
36end
New Pastebin Post

1local HttpService = game:GetService("HttpService")
2
3local URL_PASTEBIN_NEW_PASTE = "https://pastebin.com/api/api_post.php"
4local dataFields = {
5 -- Pastebin API developer key from
6 -- https://pastebin.com/api#1
7 ["api_dev_key"] = "FILL THIS WITH YOUR API DEVELOPER KEY",
8
9 ["api_option"] = "paste", -- keep as "paste"
10 ["api_paste_name"] = "HttpService:PostAsync", -- paste name
11 ["api_paste_code"] = "Hello, world", -- paste content
12 ["api_paste_format"] = "text", -- paste format
13 ["api_paste_expire_date"] = "10M", -- expire date
14 ["api_paste_private"] = "0", -- 0=public, 1=unlisted, 2=private
15 ["api_user_key"] = "", -- user key, if blank post as guest
16}
17
18-- The pastebin API uses a URL encoded string for post data
19-- Other APIs might use JSON, XML or some other format
20local data = ""
21for k, v in pairs(dataFields) do
22 data = data .. ("&%s=%s"):format(HttpService:UrlEncode(k), HttpService:UrlEncode(v))
23end
24data = data:sub(2) -- Remove the first &
25
26-- Here's the data we're sending
27print(data)
28
29-- Make the request
30local response = HttpService:PostAsync(URL_PASTEBIN_NEW_PASTE, data, Enum.HttpContentType.ApplicationUrlEncoded, false)
31-- The response will be the URL to the new paste (or an error string if something was wrong)
32print(response)
Astronauts in Space

1local HttpService = game:GetService("HttpService")
2
3local URL_ASTROS = "http://api.open-notify.org/astros.json"
4
5-- Make the request to our endpoint URL
6local response = HttpService:GetAsync(URL_ASTROS)
7
8-- Parse the JSON response
9local data = HttpService:JSONDecode(response)
10
11-- Information in the data table is dependent on the response JSON
12if data.message == "success" then
13 print("There are currently " .. data.number .. " astronauts in space:")
14 for i, person in pairs(data.people) do
15 print(i .. ": " .. person.name .. " is on " .. person.craft)
16 end
17end

Summary

Properties

Indicates whether http request can be sent to external websites.

Events

Methods

GenerateGUID(wrapInCurlyBraces: boolean): string  

Generates a UUID/GUID random string, optionally with curly braces.


Decodes a JSON string into a Lua table.

JSONEncode(input: Variant): string  CUSTOM LUA STATE

Generate a JSON string from a Lua table.

SetHttpEnabled(enabled: boolean): void  


UrlEncode(input: string): string  

Replaces URL-unsafe characters with '%' and two hexadecimal characters.

GetAsync(url: string, nocache: boolean, headers: Variant): string  YIELDS

Send an HTTP GET request.

PostAsync(url: string, data: string, content_type: HttpContentType, compress: boolean, headers: Variant): string  YIELDS

Performs a HTTP POST request.

RequestAsync(requestOptions: table): table  YIELDS

Sends an HTTP request using any HTTP method given a dictionary of information.

Properties

HttpEnabled

When set to true, you are able to send requests to other websites using HttpService:GetAsync(), HttpService:PostAsync(), and HttpService:RequestAsync().

To enable HTTP requests, the HttpService must be enabled in Studio's Game Settings through the SecurityAllow HTTP Requests toggle.

Events

Methods

GenerateGUID

The GenerateGUID function randomly creates a universally unique identifier (UUID) string.

The sixteen octets of a UUID are represented as 32 hexadecimal (base 16) digits, displayed in 5 groups separated by hyphens in the form 8-4-4-4-12 for a total of 36 characters. For example: 123e4567-e89b-12d3-a456-426655440000.

The wrapInCurlyBraces argument determines whether the returned string is wrapped in curly braces {}. For instance:

  • true - {94b717b2-d54f-4340-a504-bd809ef5bf5c}
  • false - db454790-7563-44ed-ab4b-397ff5df737b

Parameters

wrapInCurlyBraces: boolean

Whether the returned string should be wrapped in {curly braces}.

Default Value: "true"

Returns

The randomly generated UUID.

Code Samples

HttpService GenerateGUID

1local HttpService = game:GetService("HttpService")
2
3local result = HttpService:GenerateGUID(true)
4
5print(result) --> Example output: {04AEBFEA-87FC-480F-A98B-E5E221007A90}

GetHttpEnabled

Roblox Script Security

Returns

GetUserAgent

Roblox Script Security

Returns

JSONDecode

The JSONDecode function transforms a JSON object or array into a Lua table with the following characteristics:

  • Keys of the table are strings or numbers but not both. If a JSON object contains both, string keys are ignored.
  • An empty JSON object generates an empty Lua table {}.
  • If the input string is not a valid JSON object, this function will throw an error.

To encode a Lua table into a JSON object, you can use HttpService's HttpService:JSONEncode() function.

Many web endpoints use JSON, as it is commonly used on the Internet. Visit JSON.org to become more familiar with the format.

This method can be used regardless of whether HTTP Requests are enabled.

Parameters

input: string

The JSON object being decoded.


Returns

The decoded JSON object as a Lua table.

Code Samples

HttpService JSONDecode

1local HttpService = game:GetService("HttpService")
2
3local jsonString = [[
4{
5 "message": "success",
6 "info": {
7 "points": 120,
8 "isLeader": true,
9 "user": {
10 "id": 12345,
11 "name": "JohnDoe"
12 },
13 "past_scores": [50, 42, 95],
14 "best_friend": null
15 }
16}
17]]
18
19local data = HttpService:JSONDecode(jsonString)
20
21if data.message == "success" then
22 -- Since tab["hello"] and tab.hello are equivalent,
23 -- you could also use data["info"]["points"] here:
24 print("I have " .. data.info.points .. " points")
25 if data.info.isLeader then
26 print("I am the leader")
27 end
28 print("I have " .. #data.info.past_scores .. " past scores")
29
30 print("All the information:")
31 for key, value in pairs(data.info) do
32 print(key, typeof(value), value)
33 end
34end

JSONEncode

Custom Lua State

The JSONEncode function transforms a Lua table into a JSON object or array based on the following guidelines:

  • Keys of the table must be either strings or numbers. If a table contains both, an array takes priority (string keys are ignored).

  • An empty Lua table {} generates an empty JSON array.

  • The value nil is never generated.

  • Cyclic table references cause an error.

    This function allows values such as inf and nan, which are not valid JSON. This may cause problems if you want to use the outputted JSON elsewhere.

To reverse the encoding process, and decode a JSON object, you can use HttpService's HttpService:JSONDecode() function.

Many web endpoints use JSON, as it is commonly used on the Internet. Visit JSON.org to become more familiar with the format.

This method can be used regardless of whether HTTP Requests are enabled.

Parameters

input: Variant

The input Lua table.


Returns

The returned JSON string.

Code Samples

HttpService JSONEncode

1local HttpService = game:GetService("HttpService")
2
3local tab = {
4 -- Remember: these lines are equivalent
5 --["message"] = "success",
6 message = "success",
7
8 info = {
9 points = 123,
10 isLeader = true,
11 user = {
12 id = 12345,
13 name = "JohnDoe",
14 },
15 past_scores = { 50, 42, 95 },
16 best_friend = nil,
17 },
18}
19
20local json = HttpService:JSONEncode(tab)
21print(json)

RequestInternal

Roblox Script Security

Parameters

options: table

Returns

SetHttpEnabled

void
Roblox Script Security

Parameters

enabled: boolean

Returns

void

UrlEncode

The UrlEncode function percent-encodes a given string so that reserved characters properly encoded with '%' and two hexadecimal characters.

This is useful when formatting URLs for use with HttpService:GetAsync()/HttpService:PostAsync(), or POST data of the media type application/x-www-form-urlencoded (Enum.HttpContentType.ApplicationUrlEncoded).

For instance, when you encode the URL https://www.roblox.com/discover#/, this function returns https%3A%2F%2Fwww%2Eroblox%2Ecom%2Fdiscover%23%2F.

Parameters

input: string

The string (URL) to encode.


Returns

The encoded string.

Code Samples

HttpService UrlEncode

1local HttpService = game:GetService("HttpService")
2
3local content = "Je suis allé au cinéma." -- French for "I went to the movies"
4local result = HttpService:UrlEncode(content)
5
6print(result) --> Je%20suis%20all%C3%A9%20au%20cinema%2E
New Pastebin Post

1local HttpService = game:GetService("HttpService")
2
3local URL_PASTEBIN_NEW_PASTE = "https://pastebin.com/api/api_post.php"
4local dataFields = {
5 -- Pastebin API developer key from
6 -- https://pastebin.com/api#1
7 ["api_dev_key"] = "FILL THIS WITH YOUR API DEVELOPER KEY",
8
9 ["api_option"] = "paste", -- keep as "paste"
10 ["api_paste_name"] = "HttpService:PostAsync", -- paste name
11 ["api_paste_code"] = "Hello, world", -- paste content
12 ["api_paste_format"] = "text", -- paste format
13 ["api_paste_expire_date"] = "10M", -- expire date
14 ["api_paste_private"] = "0", -- 0=public, 1=unlisted, 2=private
15 ["api_user_key"] = "", -- user key, if blank post as guest
16}
17
18-- The pastebin API uses a URL encoded string for post data
19-- Other APIs might use JSON, XML or some other format
20local data = ""
21for k, v in pairs(dataFields) do
22 data = data .. ("&%s=%s"):format(HttpService:UrlEncode(k), HttpService:UrlEncode(v))
23end
24data = data:sub(2) -- Remove the first &
25
26-- Here's the data we're sending
27print(data)
28
29-- Make the request
30local response = HttpService:PostAsync(URL_PASTEBIN_NEW_PASTE, data, Enum.HttpContentType.ApplicationUrlEncoded, false)
31-- The response will be the URL to the new paste (or an error string if something was wrong)
32print(response)

GetAsync

Yields

The GetAsync function sends an HTTP GET request. It functions similarly to RequestAsync except that it accepts HTTP request parameters as method parameters instead of a single dictionary and returns only the body of the HTTP response. Generally, this method is useful only as a shorthand and RequestAsync should to be used in most cases.

When true, the nocache parameter prevents this function from caching results from previous calls with the same url.

Parameters

url: string

The web address you are requesting data from.

nocache: boolean

Whether the request stores (caches) the response.

Default Value: "false"
headers: Variant

Used to specify some HTTP request headers.


Returns

The GET request's response body.

Code Samples

Where is the International Space Station?

1local HttpService = game:GetService("HttpService")
2
3-- Where is the International Space Station right now?
4local URL_ISS = "http://api.open-notify.org/iss-now.json"
5
6local function printISS()
7 local response
8 local data
9 -- Use pcall in case something goes wrong
10 pcall(function()
11 response = HttpService:GetAsync(URL_ISS)
12 data = HttpService:JSONDecode(response)
13 end)
14 -- Did our request fail or our JSON fail to parse?
15 if not data then
16 return false
17 end
18
19 -- Fully check our data for validity. This is dependent on what endpoint you're
20 -- to which you're sending your requests. For this example, this endpoint is
21 -- described here: http://open-notify.org/Open-Notify-API/ISS-Location-Now/
22 if data.message == "success" and data.iss_position then
23 if data.iss_position.latitude and data.iss_position.longitude then
24 print("The International Space Station is currently at:")
25 print(data.iss_position.latitude .. ", " .. data.iss_position.longitude)
26 return true
27 end
28 end
29 return false
30end
31
32if printISS() then
33 print("Success")
34else
35 print("Something went wrong")
36end
Astronauts in Space

1local HttpService = game:GetService("HttpService")
2
3local URL_ASTROS = "http://api.open-notify.org/astros.json"
4
5-- Make the request to our endpoint URL
6local response = HttpService:GetAsync(URL_ASTROS)
7
8-- Parse the JSON response
9local data = HttpService:JSONDecode(response)
10
11-- Information in the data table is dependent on the response JSON
12if data.message == "success" then
13 print("There are currently " .. data.number .. " astronauts in space:")
14 for i, person in pairs(data.people) do
15 print(i .. ": " .. person.name .. " is on " .. person.craft)
16 end
17end

PostAsync

Yields

The PostAsync function sends an HTTP POST request. It functions similarly to RequestAsync except that it accepts HTTP request parameters as method parameters instead of a single dictionary and returns only the body of the HTTP response. Generally, this method is useful only as a shorthand and RequestAsync should to be used in most cases.

When true, the compress parameter controls whether large request bodies will be compressed using gzip.

Parameters

url: string

The destination address for the data.

data: string

The data being sent.

content_type: HttpContentType

Modifies the value in the Content-Type header sent with the request.

Default Value: "ApplicationJson"
compress: boolean

Determines whether the data is compressed (gzipped) when sent.

Default Value: "false"
headers: Variant

Used to specify some HTTP request headers.


Returns

The HTTP response sent back indicating the request result.

Code Samples

New Pastebin Post

1local HttpService = game:GetService("HttpService")
2
3local URL_PASTEBIN_NEW_PASTE = "https://pastebin.com/api/api_post.php"
4local dataFields = {
5 -- Pastebin API developer key from
6 -- https://pastebin.com/api#1
7 ["api_dev_key"] = "FILL THIS WITH YOUR API DEVELOPER KEY",
8
9 ["api_option"] = "paste", -- keep as "paste"
10 ["api_paste_name"] = "HttpService:PostAsync", -- paste name
11 ["api_paste_code"] = "Hello, world", -- paste content
12 ["api_paste_format"] = "text", -- paste format
13 ["api_paste_expire_date"] = "10M", -- expire date
14 ["api_paste_private"] = "0", -- 0=public, 1=unlisted, 2=private
15 ["api_user_key"] = "", -- user key, if blank post as guest
16}
17
18-- The pastebin API uses a URL encoded string for post data
19-- Other APIs might use JSON, XML or some other format
20local data = ""
21for k, v in pairs(dataFields) do
22 data = data .. ("&%s=%s"):format(HttpService:UrlEncode(k), HttpService:UrlEncode(v))
23end
24data = data:sub(2) -- Remove the first &
25
26-- Here's the data we're sending
27print(data)
28
29-- Make the request
30local response = HttpService:PostAsync(URL_PASTEBIN_NEW_PASTE, data, Enum.HttpContentType.ApplicationUrlEncoded, false)
31-- The response will be the URL to the new paste (or an error string if something was wrong)
32print(response)

RequestAsync

Yields

The RequestAsync() function sends an HTTP request using a dictionary to specify the request data, such as the target URL, method, headers and request body data. It returns a dictionary that describes the response data received.

Request Dictionary Fields

NameTypeRequiredDescription
UrlStringyesThe target URL for this request. Must use http or https protocols.
MethodStringnoThe HTTP method being used by this request, most often GET or POST.
HeadersDictionarynoA dictionary of headers to be used with this request. Most HTTP headers are accepted here, but not all.
BodyStringnoThe request body. Can be any string, including binary data. Must be excluded when using the GET or HEAD HTTP methods. It might be necessary to specify the Content-Type header when sending JSON or other formats.

HTTP Headers

In the request dictionary, you can specify custom HTTP headers to use in the request. However, some headers cannot be specified. For example, Content-Length is determined from the request body. User-Agent and Roblox-Id are locked by Roblox. Other headers like Accept or Cache-Control use default values but can be overridden. More commonly, some REST APIs may require API keys or other service authentication to be specified in request headers.

This method does not detect the format of body content. Many web servers require the Content-Type header be set appropriately when sending certain formats. Other methods of HttpService use the HttpContentType enum; for this method set the Content-Type header appropriately: text/plain, text/xml, application/xml, application/json or application/x-www-form-urlencoded are replacement Content-Type header values for the respective enum values.

Response Dictionary Fields

The function returns a dictionary containing the following fields:

NameTypeDescription
SuccessBooleanThe success status of the request. This is true if and only if the StatusCode lies within the range [200, 299].
StatusCodeIntegerThe HTTP response code identifying the status of the response.
StatusMessageStringThe status message that was sent back.
HeadersDictionaryA dictionary of headers that were set in this response.
BodyThe request body (content) received in the response.

Error Cases

This method raises an error if the response times out or if the target server rejects the request. If a web service goes down for some reason, it can cause scripts that use this method to stop functioning altogether. It is often a good idea to wrap calls to this method in pcall and gracefully handle failure cases if the required information isn't available.

Limitations

The current limitation for sending and receiving HTTP requests is 500 requests per minute. Requests over this threshold will fail. Additionally, Roblox domains are blacklisted. This means that HTTP requests cannot be sent to any Roblox owned site, such as www.roblox.com.

Parameters

requestOptions: table

A dictionary containing information to be requested from the server specified.


Returns

A dictionary containing response information from the server specified.

Code Samples

Sending an HTTP Request

1-- Remember to set enable HTTP Requests in game settings!
2local HttpService = game:GetService("HttpService")
3
4local function request()
5 local response = HttpService:RequestAsync({
6 Url = "http://httpbin.org/post", -- This website helps debug HTTP requests
7 Method = "POST",
8 Headers = {
9 ["Content-Type"] = "application/json", -- When sending JSON, set this!
10 },
11 Body = HttpService:JSONEncode({ hello = "world" }),
12 })
13
14 if response.Success then
15 print("Status code:", response.StatusCode, response.StatusMessage)
16 print("Response body:\n", response.Body)
17 else
18 print("The request failed:", response.StatusCode, response.StatusMessage)
19 end
20end
21
22-- Remember to wrap the function in a 'pcall' to prevent the script from breaking if the request fails
23local success, message = pcall(request)
24if not success then
25 print("Http Request failed:", message)
26end