---
title: "http"
description: "The http namespace — the engine's Luau API reference for http."
section: "API Reference"
slug: "api-http"
canonical: "https://origozero.ai/docs/api-http"
updated: "2026-09-05T23:13:46.562722198+00:00"
tags: ["api", "reference"]
---

# http

The `http` namespace — 19 functions.

## globals/http/get_bytes {#globals-http-get-bytes}

```lua
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()`.

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

## globals/http/get_json {#globals-http-get-json}

```lua
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()`.

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

## globals/http/post_bytes {#globals-http-post-bytes}

```lua
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()`.

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

## globals/http/post_json {#globals-http-post-json}

```lua
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()`.

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

## globals/http/request {#globals-http-request}

```lua
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()`.

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

## globals/http/request_raw {#globals-http-request-raw}

```lua
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()`.

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

## modules/http/README {#modules-http-readme}

```lua
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 {#modules-http-get-bytes}

```lua
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).

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

## modules/http/get_json {#modules-http-get-json}

```lua
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).

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

## modules/http/post_bytes {#modules-http-post-bytes}

```lua
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).

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

## modules/http/post_json {#modules-http-post-json}

```lua
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).

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

## modules/http/request {#modules-http-request}

```lua
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).

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

## modules/http/request_raw {#modules-http-request-raw}

```lua
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).

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

## typed/builtin//modules/api/engine/http/http/get_bytes {#typed-builtin-modules-api-engine-http-http-get-bytes}

```lua
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()`.

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

## typed/builtin//modules/api/engine/http/http/get_json {#typed-builtin-modules-api-engine-http-http-get-json}

```lua
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()`.

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

## typed/builtin//modules/api/engine/http/http/post_bytes {#typed-builtin-modules-api-engine-http-http-post-bytes}

```lua
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()`.

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

## typed/builtin//modules/api/engine/http/http/post_json {#typed-builtin-modules-api-engine-http-http-post-json}

```lua
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()`.

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

## typed/builtin//modules/api/engine/http/http/request {#typed-builtin-modules-api-engine-http-http-request}

```lua
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()`.

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

## typed/builtin//modules/api/engine/http/http/request_raw {#typed-builtin-modules-api-engine-http-http-request-raw}

```lua
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()`.

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