Log inGet started

http

Updated 5 September 2026

The http namespace — 19 functions.

globals/http/get_bytes

http.get_bytes(url: string, headers: Headers?) -> PromiseId

Async HTTP GET returning raw bytes (binary-safe string). Suitable for piping into vfs.write to download a file.

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).

Returns PromiseId — Promise handle for task.await().

local bytes = task.await(http.get_bytes("https://example.com/sound.ogg"))

globals/http/get_json

http.get_json(url: string, headers: Headers?) -> PromiseId

Async HTTP GET returning JSON. Returns a promise handle — wrap with task.await() to block until the response arrives.

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).

Returns PromiseId — Promise handle for task.await().

local data = task.await(http.get_json("https://api.example.com/info"))

globals/http/post_bytes

http.post_bytes(url: string, headers: Headers?, body: JsonBody?) -> PromiseId

Async HTTP POST returning raw bytes — use for APIs that accept JSON input but return binary output (audio, images).

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body JsonBody (optional) — JSON body (optional).

Returns PromiseId — Promise handle for task.await().

local audio = task.await(http.post_bytes(ttsUrl, nil, { text = "hello" }))

globals/http/post_json

http.post_json(url: string, headers: Headers?, body: JsonBody?) -> PromiseId

Async HTTP POST returning JSON. Body is a Luau table; the FFI layer JSON-encodes it before the request goes out.

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body JsonBody (optional) — JSON body (optional).

Returns PromiseId — Promise handle for task.await().

local r = task.await(http.post_json(url, nil, { name = "Alice" }))

globals/http/request

http.request(method: string, url: string, headers: Headers?, body: JsonBody?) -> PromiseId

Async HTTP request with an arbitrary verb (GET/POST/PUT/PATCH/ DELETE/…) returning JSON. Body is a Luau table; an empty 2xx response resolves to an empty table.

Parameters

  • method string — HTTP verb (case-insensitive).
  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body JsonBody (optional) — JSON body (optional).

Returns PromiseId — Promise handle for task.await().

local w = task.await(http.request("PATCH", url, hdrs, { description = "hi" }))

globals/http/request_raw

http.request_raw(method: string, url: string, headers: Headers?, body: buffer | string | nil?) -> PromiseId

Async HTTP request with an arbitrary verb and a RAW binary request body (a binary-safe string), for content-addressed blob uploads. The resolved value is the response body text.

Parameters

  • method string — HTTP verb (case-insensitive).
  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body buffer | string | nil (optional) — Raw binary request body (optional).

Returns PromiseId — Promise handle for task.await().

local r = task.await(http.request_raw("POST", blobsUrl, hdrs, pngBytes))

modules/http/README

require("@builtin/modules/api/engine/http") -- http (also available as global 'http')

Async HTTP — GET/POST returning JSON or raw bytes. Public Luau surface over the __http Internal FFI namespace.

Usage: local http = require("@builtin/modules/api/engine/http") Also available as global: http

modules/http/get_bytes

get_bytes(url: string, headers: Headers?): PromiseId

Async HTTP GET returning raw bytes (binary-safe string). Suitable for piping into vfs.write to download a file.

Parameters

  • url string — Request URL.
  • headers Headers? (optional) — Header key-value pairs (optional).
local bytes = task.await(http.get_bytes("https://example.com/sound.ogg"))

modules/http/get_json

get_json(url: string, headers: Headers?): PromiseId

Async HTTP GET returning JSON. Returns a promise handle — wrap with task.await() to block until the response arrives.

Parameters

  • url string — Request URL.
  • headers Headers? (optional) — Header key-value pairs (optional).
local data = task.await(http.get_json("https://api.example.com/info"))

modules/http/post_bytes

post_bytes(url: string, headers: Headers?, body: JsonBody?): PromiseId

Async HTTP POST returning raw bytes — use for APIs that accept JSON input but return binary output (audio, images).

Parameters

  • url string — Request URL.
  • headers Headers? (optional) — Header key-value pairs (optional).
  • body JsonBody? (optional) — JSON body (optional).
local audio = task.await(http.post_bytes(ttsUrl, nil, { text = "hello" }))

modules/http/post_json

post_json(url: string, headers: Headers?, body: JsonBody?): PromiseId

Async HTTP POST returning JSON. Body is a Luau table; the FFI layer JSON-encodes it before the request goes out.

Parameters

  • url string — Request URL.
  • headers Headers? (optional) — Header key-value pairs (optional).
  • body JsonBody? (optional) — JSON body (optional).
local r = task.await(http.post_json(url, nil, { name = "Alice" }))

modules/http/request

request(method: string, url: string, headers: Headers?, body: JsonBody?): PromiseId

Async HTTP request with an arbitrary verb (GET/POST/PUT/PATCH/ DELETE/…) returning JSON. Body is a Luau table; an empty 2xx response resolves to an empty table.

Parameters

  • method string — HTTP verb (case-insensitive).
  • url string — Request URL.
  • headers Headers? (optional) — Header key-value pairs (optional).
  • body JsonBody? (optional) — JSON body (optional).
local w = task.await(http.request("PATCH", url, hdrs, { description = "hi" }))

modules/http/request_raw

request_raw(method: string, url: string, headers: Headers?, body: buffer | string | nil): PromiseId

Async HTTP request with an arbitrary verb and a RAW binary request body (a binary-safe string), for content-addressed blob uploads. The resolved value is the response body text.

Parameters

  • method string — HTTP verb (case-insensitive).
  • url string — Request URL.
  • headers Headers? (optional) — Header key-value pairs (optional).
  • body buffer | string | nil (optional) — Raw binary request body (optional).
local r = task.await(http.request_raw("POST", blobsUrl, hdrs, pngBytes))

typed/builtin//modules/api/engine/http/http/get_bytes

http.get_bytes(url: string, headers: Headers?) -> PromiseId

Async HTTP GET returning raw bytes (binary-safe string). Suitable for piping into vfs.write to download a file.

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).

Returns PromiseId — Promise handle for task.await().

local bytes = task.await(http.get_bytes("https://example.com/sound.ogg"))

typed/builtin//modules/api/engine/http/http/get_json

http.get_json(url: string, headers: Headers?) -> PromiseId

Async HTTP GET returning JSON. Returns a promise handle — wrap with task.await() to block until the response arrives.

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).

Returns PromiseId — Promise handle for task.await().

local data = task.await(http.get_json("https://api.example.com/info"))

typed/builtin//modules/api/engine/http/http/post_bytes

http.post_bytes(url: string, headers: Headers?, body: JsonBody?) -> PromiseId

Async HTTP POST returning raw bytes — use for APIs that accept JSON input but return binary output (audio, images).

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body JsonBody (optional) — JSON body (optional).

Returns PromiseId — Promise handle for task.await().

local audio = task.await(http.post_bytes(ttsUrl, nil, { text = "hello" }))

typed/builtin//modules/api/engine/http/http/post_json

http.post_json(url: string, headers: Headers?, body: JsonBody?) -> PromiseId

Async HTTP POST returning JSON. Body is a Luau table; the FFI layer JSON-encodes it before the request goes out.

Parameters

  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body JsonBody (optional) — JSON body (optional).

Returns PromiseId — Promise handle for task.await().

local r = task.await(http.post_json(url, nil, { name = "Alice" }))

typed/builtin//modules/api/engine/http/http/request

http.request(method: string, url: string, headers: Headers?, body: JsonBody?) -> PromiseId

Async HTTP request with an arbitrary verb (GET/POST/PUT/PATCH/ DELETE/…) returning JSON. Body is a Luau table; an empty 2xx response resolves to an empty table.

Parameters

  • method string — HTTP verb (case-insensitive).
  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body JsonBody (optional) — JSON body (optional).

Returns PromiseId — Promise handle for task.await().

local w = task.await(http.request("PATCH", url, hdrs, { description = "hi" }))

typed/builtin//modules/api/engine/http/http/request_raw

http.request_raw(method: string, url: string, headers: Headers?, body: buffer | string | nil?) -> PromiseId

Async HTTP request with an arbitrary verb and a RAW binary request body (a binary-safe string), for content-addressed blob uploads. The resolved value is the response body text.

Parameters

  • method string — HTTP verb (case-insensitive).
  • url string — Request URL.
  • headers Headers (optional) — Header key-value pairs (optional).
  • body buffer | string | nil (optional) — Raw binary request body (optional).

Returns PromiseId — Promise handle for task.await().

local r = task.await(http.request_raw("POST", blobsUrl, hdrs, pngBytes))
  • api
  • reference