Skip to main content
Version: Unreleased

HTTP API

HTTP client helpers are available under ptool.http and p.http.

ptool.http.request​

v0.1.0 - Introduced.

ptool.http.request(options) sends an HTTP request and returns a Response object.

options fields:

  • url (string, required): The request URL.
  • method (string, optional): The HTTP method. Defaults to "GET".
  • headers (table, optional): Request headers, where both keys and values are strings.
  • query (table, optional): Query parameters appended to the request URL. Keys must be strings. Values may be strings, numbers, or booleans.
  • body (string, optional): The request body.
  • json (Lua value, optional): A Lua value encoded as JSON and used as the request body. When content-type is not already set, it defaults to application/json.
  • form (table, optional): Form fields encoded as application/x-www-form-urlencoded and used as the request body. Keys must be strings. Values may be strings, numbers, or booleans.
  • timeout_ms (integer, optional): Timeout in milliseconds. Defaults to 30000.
  • connect_timeout_ms (integer, optional): Connection timeout in milliseconds.
  • follow_redirects (boolean, optional): Whether redirects should be followed.
  • max_redirects (integer, optional): Maximum number of redirects to follow.
  • user_agent (string, optional): Sets the user-agent request header.
  • basic_auth (table, optional): HTTP basic auth credentials with string fields username and password.
  • bearer_token (string, optional): Bearer token used for the authorization header.
  • fail_on_http_error (boolean, optional): When true, raise an error for 4xx and 5xx HTTP responses. Defaults to false.

Notes:

  • body, json, and form are mutually exclusive.
  • basic_auth and bearer_token are mutually exclusive.

Example:

local resp = ptool.http.request({
  url = "https://httpbin.org/post",
  method = "POST",
  query = {
    page = 1,
    draft = false,
  },
  json = {
    name = "alice",
    tags = {"admin", "beta"},
  },
  user_agent = "ptool-script/1.0",
  fail_on_http_error = true,
})

print(resp.status, resp.ok)
print(resp:header("content-type"))
local data = resp:json()
print(data.json.name)

Response​

v0.1.0 - Introduced.

Response represents an HTTP response returned by ptool.http.request(...).

Fields:

  • status (integer): The HTTP status code.
  • ok (boolean): Whether the status code is in the 2xx range.
  • url (string): The final URL after redirects.
  • headers (table): A flattened convenience view of response headers (table<string, string>). Repeated headers are merged with , .

Methods:

  • resp:text(): Reads and returns the response body as text.
  • resp:json(): Reads the response body, parses it as JSON, and returns a Lua value.
  • resp:bytes(): Reads and returns the raw bytes (as a Lua string).
  • resp:header(name): Returns the first matching response header value, or nil.
  • resp:header_values(name): Returns all matching response header values as an array.
  • resp:raise_for_status(): Raises an error for 4xx and 5xx HTTP responses.

text​

Canonical API name: ptool.http.Response:text.

resp:text() reads and returns the response body as text.

  • Returns: string.

json​

Canonical API name: ptool.http.Response:json.

resp:json() reads the response body, parses it as JSON, and returns a Lua value.

bytes​

Canonical API name: ptool.http.Response:bytes.

resp:bytes() reads and returns the response body as raw bytes.

  • Returns: string.

Canonical API name: ptool.http.Response:header.

resp:header(name) returns the first response header value matching name.

  • name (string, required): The header name to look up.
  • Returns: string | nil.

header_values​

Canonical API name: ptool.http.Response:header_values.

resp:header_values(name) returns all response header values matching name.

  • name (string, required): The header name to look up.
  • Returns: string[].

raise_for_status​

Canonical API name: ptool.http.Response:raise_for_status.

resp:raise_for_status() raises an error when the response status code is in the 4xx or 5xx range.

Notes:

  • Non-2xx HTTP statuses do not raise errors by default. Callers can check resp.ok, set fail_on_http_error = true, or call resp:raise_for_status().
  • The response body is cached after the first read. Calling text, json, and bytes multiple times is allowed.