http

Async HTTP — GET/POST returning JSON or raw bytes.

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

The http namespace: 18 functions.

globals/http/get_bytes

http.get_bytes(url: string, headers: Headers?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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

globals/http/get_json

http.get_json(url: string, headers: Headers?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> PromiseId

Async HTTP GET returning JSON. Returns a future (a PromiseHandle) at once, with the request in flight: keep it, f:await() (or task.await(f)) when the response is needed, and f:state() to see whether it has arrived without waiting.

Parameters

• url string — Request URL.
• headers Headers (optional) — Header key-value pairs (optional).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

local data = task.await(http.get_json("https://api.example.com/info"))
local record = task.await(http.get_json(recordUrl, nil, nil, { 404 })) -- a missing record is an answer

globals/http/post_bytes

http.post_bytes(url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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

globals/http/post_json

http.post_json(url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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

globals/http/request

http.request(method: string, url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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

modules/http/get_bytes

get_bytes(url: string, headers: Headers?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?): 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).
• timeoutMs TimeoutMs? (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses? (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

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

modules/http/get_json

get_json(url: string, headers: Headers?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?): PromiseId

Async HTTP GET returning JSON. Returns a future (a PromiseHandle) at once, with the request in flight: keep it, f:await() (or task.await(f)) when the response is needed, and f:state() to see whether it has arrived without waiting.

Parameters

• url string — Request URL.
• headers Headers? (optional) — Header key-value pairs (optional).
• timeoutMs TimeoutMs? (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses? (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

local data = task.await(http.get_json("https://api.example.com/info"))
local record = task.await(http.get_json(recordUrl, nil, nil, { 404 })) -- a missing record is an answer

modules/http/post_bytes

post_bytes(url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?): 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).
• timeoutMs TimeoutMs? (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses? (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

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

modules/http/post_json

post_json(url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?): 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).
• timeoutMs TimeoutMs? (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses? (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

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

modules/http/request

request(method: string, url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?): 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).
• timeoutMs TimeoutMs? (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses? (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (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, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?): 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).
• timeoutMs TimeoutMs? (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses? (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (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?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> PromiseId

Async HTTP GET returning JSON. Returns a future (a PromiseHandle) at once, with the request in flight: keep it, f:await() (or task.await(f)) when the response is needed, and f:state() to see whether it has arrived without waiting.

Parameters

• url string — Request URL.
• headers Headers (optional) — Header key-value pairs (optional).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

local data = task.await(http.get_json("https://api.example.com/info"))
local record = task.await(http.get_json(recordUrl, nil, nil, { 404 })) -- a missing record is an answer

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

http.post_bytes(url: string, headers: Headers?, body: JsonBody?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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?, timeoutMs: TimeoutMs?, expectedStatuses: ExpectedStatuses?) -> 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).
• timeoutMs TimeoutMs (optional) — How long the request is given to be answered, in milliseconds; the engine's own bound when left out, none when 0 (optional).
• expectedStatuses ExpectedStatuses (optional) — HTTP statuses this caller handles as an answer it expected, e.g. { 404 }: a response with one settles the future as any other non-2xx does and is logged as information rather than an error (optional).

Returns PromiseId — A future (PromiseHandle): f:await() or task.await(f) delivers the response, f:state() reads whether it has.

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