# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: HttpService type: class memory_category: Instances summary: | Allows sending HTTP requests and provides various web-related and JSON methods. description: | `HttpService` allows HTTP requests to be sent from experience servers using `Class.HttpService:RequestAsync()|RequestAsync`, `Class.HttpService:GetAsync()|GetAsync` and `Class.HttpService:PostAsync()|PostAsync`. This service allows experiences to be integrated with third-party web services such as analytics, data storage, remote server configuration, error reporting, advanced calculations, or real-time communication. Additionally, it can call a subset of the Open Cloud APIs. For more information about these use cases, see [In-experience HTTP requests](../../../cloud-services/http-service.md). `HttpService` also houses the `Class.HttpService:JSONEncode()|JSONEncode` and `Class.HttpService:JSONDecode()|JSONDecode` methods, which are useful for communicating with services that use the [JSON](https://json.org) format. In addition, the `Class.HttpService:GenerateGUID()|GenerateGUID` method provides random 128‑bit labels which can be treated as probabilistically unique in a variety of scenarios. Within Studio, use `Class.HttpService:CreateWebStreamClient()|CreateWebStreamClient()` to process data in real time from servers that support streaming protocols such as [SSE](https://en.wikipedia.org/wiki/Server-sent_events), [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding), and [WebSockets](https://en.wikipedia.org/wiki/WebSocket). You can connect callback functions to stream events, allowing you to process data immediately as it arrives instead of waiting for the entire response to complete. Only send HTTP requests to trusted third-party platforms to avoid introducing unnecessary security risks to your experience. code_samples: - Astronauts-in-Space - International-Space-Station - HttpService-Pastebin - OpenCloud-via-HttpService inherits: - Instance descendants: [] tags: - NotCreatable - Service deprecation_message: '' properties: - name: HttpService.HttpEnabled summary: | Indicates whether HTTP requests can be sent to external websites. description: | When set to `true`, allows scripts to send requests to websites using `Class.HttpService:GetAsync()`, `Class.HttpService:PostAsync()`, and `Class.HttpService:RequestAsync()`. This property must be toggled on through the [Experience Settings](../../../studio/experience-settings.md) interface in Studio, or for **unpublished** experiences by setting this property to `true` using the [Command Bar](../../../studio/ui-overview.md#command-bar): `game:GetService("HttpService").HttpEnabled = true` code_samples: [] type: boolean tags: [] deprecation_message: '' security: read: None write: LocalUserSecurity thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - Network methods: - name: HttpService:CreateWebStreamClient summary: | Creates a client that opens a persistent connection to stream data. description: | This method creates a client that establishes a long-lived connection to servers utilizing various streaming technologies, such as [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). After the connection is established, the client fires signals that you can connect callback functions to with `Datatype.RBXScriptConnection`. Use these callbacks to process messages as soon as they arrive, as well as respond to open, close, and error events. There is a limit of six total clients allowed at one time. Close streams that you no longer need with `Class.WebStreamClient:Close()`. When the stream is no longer needed, you should disconnect any associated `Datatype.RBXScriptConnection|RBXScriptConnections` to avoid memory leaks. This method is available in Studio only. If you use it inside scripts, make sure to remove any references before publishing the experience. We encourage you to create plugins with this feature for reusability and ease of use. code_samples: - HttpService-CreateSSEWebStreamClient - HttpService-CreateRawStreamWebStreamClient parameters: - name: streamClientType type: WebStreamClientType default: summary: | The type of streaming connection to intiialize the client with. - name: requestOptions type: Dictionary default: summary: | A dictionary containing information to be requested from the server. It is identical to `requestOptions` in `Class.HttpService:RequestAsync()`. returns: - type: WebStreamClient summary: | A stateful client that emits events in the stream lifecycle. tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Network - name: HttpService:GenerateGUID summary: | Generates a UUID/GUID random string, optionally with curly braces. description: | This method generates a **random universally unique identifier** ([UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier)) string. The sixteen octets of a UUID are represented as 32 hexadecimal (base 16) digits, displayed in five 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 UUID specification used is [Version 4 (random)](), variant 1 (DCE 1.1, ISO/IEC 11578:1996). UUIDs of this version are the most commonly used due to their simplicity, as they are entirely randomly generated. Note that this version does not have certain features that other UUID versions have, such as encoded timestamps, MAC addresses, or time-based sorting like [UUIDv7](https://uuid7.com/) or [ULID](https://github.com/ulid/spec). There are over 5.3×1036 unique v4 UUIDs, in which the probability of finding a duplicate within 103 trillion UUIDs is one in a billion. 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` code_samples: - HttpService-GenerateGUID parameters: - name: wrapInCurlyBraces type: boolean default: true summary: | Whether the returned string should be wrapped in curly braces (`{}`). returns: - type: string summary: | The randomly generated UUID. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: [] - name: HttpService:GetAsync summary: | Sends an HTTP `GET` request. description: | This method sends an HTTP `GET` request. It functions similarly to `Class.HttpService:RequestAsync()|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 `Class.HttpService:RequestAsync()|RequestAsync()` should be used in most cases. When `true`, the `nocache` parameter prevents this method from caching results from previous calls with the same `url`. code_samples: - Astronauts-in-Space - International-Space-Station parameters: - name: url type: Variant default: summary: | The web address you are requesting data from. - name: nocache type: boolean default: false summary: | Whether the request stores (caches) the response. - name: headers type: Variant default: summary: | Used to specify some HTTP request headers. returns: - type: string summary: | The GET request's response body. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Network - name: HttpService:GetSecret summary: | Returns a `Datatype.Secret` from the secrets store. description: | This method returns a value previously added to the secrets store for the experience. The secret content is not printable and not available when the experience runs locally. The returned `Datatype.Secret` can be transformed using built-in methods such as `Datatype.Secret:AddPrefix()`. It is expected to be sent as a part of an HTTP request. For more information, see the [usage guide](../../../cloud-services/secrets.md). code_samples: [] parameters: - name: key type: string default: summary: '' returns: - type: Secret summary: '' tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Network - name: HttpService:JSONDecode summary: | Decodes a JSON string into a Luau table. description: | This method transforms a JSON object or array into a Luau [table](../../../luau/tables.md) 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 Luau table (`{}`). - If the `input` string is not a valid JSON object, this method will throw an error. To encode a Luau table into a JSON object, use the `Class.HttpService:JSONEncode()` method. This method can be used regardless of whether HTTP requests are enabled. code_samples: - HttpService-JSONDecode parameters: - name: input type: string default: summary: | The JSON object being decoded. returns: - type: Variant summary: | The decoded JSON object as a Luau table. tags: - CustomLuaState deprecation_message: '' security: None thread_safety: Safe capabilities: [] - name: HttpService:JSONEncode summary: | Generate a JSON string from a Luau table. description: | This method transforms a Luau [table](../../../luau/tables.md) 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 Luau table (`{}`) generates an empty JSON array (e.g. `[]`). - The value `nil` is never generated. - Cyclic table references cause an error. This method 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. This method also accepts `Library.buffer|buffers`, which it encodes to base64 (and often compresses) before converting to a JSON object. To reverse the encoding process and decode a JSON object, use the `Class.HttpService:JSONDecode()` method. This method can be used regardless of whether HTTP requests are enabled. code_samples: - HttpService-JSONEncode parameters: - name: input type: Variant default: summary: | The input Luau table. returns: - type: string summary: | The returned JSON string. tags: - CustomLuaState deprecation_message: '' security: None thread_safety: Safe capabilities: [] - name: HttpService:PostAsync summary: | Sends an HTTP `POST` request. description: | This method sends an HTTP `POST` request. It functions similarly to `Class.HttpService:RequestAsync()|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 `Class.HttpService:RequestAsync()|RequestAsync()` should be used in most cases. When `true`, the `compress` parameter controls whether large request bodies will be compressed using **gzip**. code_samples: - HttpService-Pastebin parameters: - name: url type: Variant default: summary: | The destination address for the data. - name: data type: string default: summary: | The data being sent. - name: content_type type: HttpContentType default: ApplicationJson summary: | Modifies the value in the `Content-Type` header sent with the request. - name: compress type: boolean default: false summary: | Determines whether the data is compressed (**gzipped**) when sent. - name: headers type: Variant default: summary: | Used to specify some HTTP request headers. returns: - type: string summary: | The HTTP response sent back indicating the request result. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Network - name: HttpService:RequestAsync summary: | Sends an HTTP request using any HTTP method given a dictionary of information. description: | This method 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. Optionally, the request can be compressed using `Enum.HttpCompression`. ##### Request dictionary fields
Name Type Required Description
Url String yes The target URL for this request. Must use http or https protocols.
Method String no The HTTP method being used by this request, most often GET or POST.
Headers Dictionary no A dictionary of headers to be used with this request. Most HTTP headers are accepted here, but not all.
Body String no The 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.
Compress Enum.HttpCompression no An optional compression field that will compress the data in the request. The value can either be Enum.HttpCompression.None or Enum.HttpCompression.Gzip.
##### Supported HTTP methods The HTTP request methods specify the purpose of the request being made and what is expected if the request is successful. For instance, the `GET` request method tells the server at the requested address that a resource is being requested and, if it succeeds, the resource at that address will be returned. Similarly, the `HEAD` request method does the same except the server knows to return a response without a `Body` element.
Method Description Safe
GET  ⓘ The GET method requests the resource at the specified address. Does not support use of the Body parameter. Yes
HEAD  ⓘ The HEAD method requests a response identical to a GET request, but with no response body. Does not support use of the Body parameter. Yes
POST  ⓘ The POST method submits the supplied Body data to the requested address. No
PUT  ⓘ The PUT method replaces all current iterations of the resource specified within the supplied Body data. No
DELETE  ⓘ The DELETE method deletes the resource specified in the supplied Body data at the requested address. No
OPTIONS  ⓘ The OPTIONS method requests the permitted communication options for the supplied address. Yes
TRACE  ⓘ The TRACE method performs a message loop-back test along the path to the resource specified in the supplied Body data. Yes
PATCH  ⓘ The PATCH method applies partial changes to the resource specified in the supplied Body data at the requested address. No
##### 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. The `RequestAsync()` 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 `Class.HttpService` use the `Enum.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 `RequestAsync()` returns a dictionary containing the following fields:
Name Type Description
Success Boolean The success status of the request. This is true if and only if the StatusCode lies within the range 200-299.
StatusCode Integer The HTTP response code identifying the status of the response.
StatusMessage String The status message that was sent back.
Headers Dictionary A dictionary of headers that were set in this response.
Body The request body (content) received in the response.
##### Error Cases `RequestAsync()` 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 `Global.LuaGlobals.pcall()` and gracefully handle failure cases if the required information isn't available. ##### Limitations The current limitation for sending and receiving **external** HTTP requests is 500 requests per minute. There is also a separate limit of 2500 requests per minute for [Open Cloud requests](../../../cloud-services/http-service.md#use-with-open-cloud). Requests over these thresholds will fail. code_samples: - sending-an-http-request - OpenCloud-via-HttpService parameters: - name: requestOptions type: Dictionary default: summary: | A dictionary containing information to be requested from the server specified. returns: - type: Dictionary summary: | A dictionary containing response information from the server specified. tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - Network - name: HttpService:UrlEncode summary: | Replaces URL-unsafe characters with '%' and two hexadecimal characters. description: | This method [percent-encodes](https://en.wikipedia.org/wiki/Percent-encoding) a given string so that reserved characters properly encoded with `%` and two hexadecimal characters. This is useful when formatting URLs for use with `Class.HttpService:GetAsync()`/`Class.HttpService:PostAsync()`, or `POST` data of the media type `application/x-www-form-urlencoded` (`Enum.HttpContentType|Enum.HttpContentType.ApplicationUrlEncoded`). For instance, when you encode the URL `https://www.roblox.com/discover#/`, this method returns `https%3A%2F%2Fwww%2Eroblox%2Ecom%2Fdiscover%23%2F`. code_samples: - HttpService-UrlEncode - HttpService-Pastebin parameters: - name: input type: string default: summary: | The string (URL) to encode. returns: - type: string summary: | The encoded string. tags: [] deprecation_message: '' security: None thread_safety: Safe capabilities: - Network events: [] callbacks: []